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ERAC CO. 



P.O. Box 1108, 14179 Halper Road 
Poway, California 92064 • (619) 679-8360 



Baby 386-20/24 
Motherboard 

One 32 bit-slot, Five 16-bit slot Two 8-blt slot Maximum 
8 meg on board (1 meg SIMMS). OK on board. 80287 or 
80387 or Weitec Co-Processor slot. Shadow RAM. 

-20 $630 -24 $650 

1 meg SIMMS-80ns $115 



16 BIT VGA Card 

RESOLUTION COLOR 

640x480 256 of 256* 

800x600 16of256* 

1024x768 16of256" 

*with 512K RAM 

Runs all standard VGA modes, 256K RAM on board. 
Drivers for AutoCad, Lotus, Framework, GEM, VP, WP, 
WS & MS Windows. 1 year warranty. 

For 51 2K $30 extra $1 85 



MOTHERBOARDS 386DX/SX/286 

DX5000 386/25MHZ-32K Cache-16 Meg-Simms-AMI Bios-Full $996 

DX4000 386/20/24MHZ Shadow-8 Meg-Simms-AMI-Baby 630/650 

P9400 386SX/16MHZ 8 Meg-Simms-Phoenix-Bios-Baby 375 

P9200 386SX/16MHZ 2 Meg-Dip-AMI-Bios-Baby 365 

SUPABOARD 286712MHz 4 Meg-Dip-Dallas Clk-AMI-Baby 197 

I/O, KB, CONTROLLERS, Etc. 

XT Enhanced Hard Disk Drive Controller with Cables 48 

DC-11M AT Hard/Floppy Contr. 1:1 438Kb/Sec, To 2048 Cyl 93 

AT I/O PLUS 1 Par(Lpt 1-3), 2 Ser(Com 1-4), Game, Cables, Ser 2(opt) 38 

VGA-16 16-bit VGA Board 800x600 with Driver Software 118 

2400 Baud External Modem, with Software and Manual 99 

KB5161 AT/XT 101 Keyboard, Cherry Keyswitehes (Click) 47 

COLORMOUSE Black-Red-Blue-Beige-Green-Yellow, Software i Manual 39 

VOICE MASTER KEY, Add voice commands to software XT/AT 1 47 

MONITORS 

VGA 1489 1024x768, .28 Dot 14", Swivel, 

Hot. 31/35KHZ, Vert 50, 60, 70, 87 Hz 430 

CASES 

MINI-TOWER, 230 W, Reset, Turbo, Keylock, Speaker 143 

TOWER, 230W, Reset, Turbo (2 Dgt), Keylock, Speaker 229 



KAYPRO Equipment 
Bargains 

9* Green Monltor-83, 84, K16 $60 

Host Interface Board 15 

Keyboard 50 

Replacement Power Supply 70 

Dnvetek 2.6M FDD (Robie or K4X) 75 



We Repair CPM Kaypros 

CPM COMPUTERS 

K4-84 425 

K10 495 

K4X 425 

We carry all IC's for Kaypro 
repair. 



IC's 

81 -189 Video Pal $15 

81-194RAMPal 15 

81-Series Char. Gen. ROMs 10 

81-Senes Monitor ROMs 10 



Test Equipment 

OSCILLOSCOPES 

TEK 7403N/7A1 8N/7B50A 60 MHz . . . $650 
Leader LB0520 30 meg Dual Trace ....300 

TEK 475 Dual Trace 200 MHz 1250 

Scope Probe xl.xlO 100MHz 25 

ANALYZERS 

TEK 491 10MHz-40GHz $3500 

HP851B/8551B10HMZ-40GHZ 1500 

Bbmation 805 Waveform Rcrdr 195 

BiomatJon 81 00 2 -Channel 

Waveform Recorder 295 

HP1600A Logic Analyzer 16ch 295 

HP1600A/1607A Logic Analyzer 32ch . . 495 
Gould K4032ch Logic Analyzer 750 

MISCELLANEOUS 

Optronics 550 MHz FreqCntr $95 

Heatgun120Vac7A 35 

TERMINALS 

Televideo 925 $99.00 



NiCds 

AA Cells 6ah $1.00 

12V Pack AA Cells .7ah 6.50 

Sub-C Cells 1.5ah 1.50 

12VPackSub-C 10.00 

Double D Cell 2.5V 4ah unused 8.00 

CCells 1.75 

7.2VRC-Pack 1.2ah 18.00 

GEL CELLS 

6V5ah 5.00 

6V8ah .'...6.00 

12V15ah 15.00 

12V2.5ah 8.50 

DCell2.5ah 2.00 

ROBOTICS 

5V DC Gear Motor w/Tacn1 , x2* $7.50 

Z80 Controller with 8-bit A/D 15.00 

12V Gear Motor 30 RPM 7.50 

Cable: DB9M-DB9F V length 2.00 

High Voltage Power Supply 

Input 15-30V DC 

Output 100V 400V 16KV 6.50 



SWITCHERS 

AT 200W Puis, tested $35.00 

5V/75, 12V/6, -12V/3, -5V/5 85.00 

5V/9.5A, 12V/3.8A, -12V/.8A 39.00 

5V/3A, 12V/2A, -12V/.4A 19.50 

5V/6A, 12V/2A, -12V/1A 29.00 

5V/6A, 24V/1 1/4A, 12V/.6A, -12V/.6A . . 29.00 

5V/30A 39.00 

5V/100A 100.00 

5V/120A 110.00 

HP DC/DC 12V1n,5V/8A,12V/5A,-5v7.3A . 45.00 

VERSATEC 8222F 22" 

Electrostatic Printer Plotter 

200 dots per inch. Up to D size. 

1" per second $2,999 

AT 80286-6 CPU BOARD 

with reset and mono/color switch. Connector for 
KB, Battery & SPKR. Phoenix Bios (tested with 
Award 3.03), 6MHz, can be upgraded to 8 or 
10MHz. Use with backplane, add memory 
board, I/O board, etc. 
ONLY $99 
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Do You Remember... 

I've been cleaning up and rearranging, 
and kept stumbling over a pile of Byte 
magazines. I dropped the subscription two 
years ago, but still had a seven year accu- 
mulation. I decided that most of the infor- 
mation was outdated and that it was time 
to clip what I wanted and discard the rest. 

It was interesting to note that I saved 
more from the older issues than I did from 
the more recent ones. I clipped Ciarcia's 
Circuit Cellar from every issue — most is- 
sues that was the only thing worth saving. 
Byte made a serious error when they lost 
Ciarcia, but it was to our advantage be- 
cause he started his own magazine, Circuit 
Cellar INK. You should definitely sub- 
scribe to it if you read his articles in Byte 
or if you enjoy hardware projects. Contact 
them at Circuit Cellar INK, 4 Park Street, 
Suite 20, Vernon, CT 06066, (203) 875- 
2751. 

The clipping process took much longer 
than I expected because I got sidetracked 
by ads. Ads for Apple II and CP/M re- 
minded me of where we were a few years 
ago. Then there were ads for CP/M86 and 
the p-System (anyone else remember 
that?) Other familiar names were Morrow, 
CompuPro, Sinclair, TeleVideo, North- 
Star, Commodore, Tarbell, Cromemco, 
Osborne, and Victor. 

I had forgotten how much change had 
occurred during the past decade, until I 
saw history flash before me as I thumbed 
through the magazines. It made me won- 
der if the changes during this decade will 
be as dramatic as those in the past decade. 
In the year 2000, which names will make 
us say "Do you remember..?" 

TCJ's Toolkit 

People frequently ask us what tools we 
use, as though we had all the answers. 
While we don't have all the answers, we do 
have the opportunity to examine a lot of 
products before selecting the ones we will 
work with. 

If anyone tells you that they are com- 
pletely objective in selecting tools, don't 
believe them. We all have our own per- 
sonal preferences and are very subjective 
when making decisions. You and I have 
different methods of working, and differ- 
ent priorities. Some of us like to partici- 
pate and take part in what we are doing 
while others want to stay at a distance and 
not become involved. Some are impressed 



by flashy colors and lots of chrome while 
others look for rock solid performance. 

Everyone wants the most that they can 
obtain for their money, but there is a dif- 
ference between value and cheap. I once 
saved a few dollars when replacing a drive 
motor on a production line conveyor belt, 
only to have the cheap motor fail a few 
days later. About 50 production line work- 
ers sat around smoking and drinking pop 
(and collecting full pay!) while I struggled 
to install a better motor. While I was doing 
this my boss kept telling me how much the 
cheap motor was costing in lost wages, and 
explained the difference between cheap 
and value. I look for tools which have good 
value, but cheap ones are worthless if they 
fail to do their job. As one rancher ex- 
plained, "If you want first class oats, you 
pay a first class price. However, if you'll 
settle for oats that been thru the horse 
once, they come a lot cheaper." 

To make or to buy is another decision 
which must be faced in many situations. I 
don't think that anyone would try to build 
a disk drive, unless they were an inventor 
attempting to develop something new. 
That decision is easy. But, the answer is 
not as apparent for things such as 
EPROM burners, EPROM erasers, ROM 
emulators, development boards, etc. On 
these we each have to make our own deci- 
sion. Sometimes we'll decide to build 
something in order to learn how to do it. 

In addition to value and the correct 
quality for the applications, I prefer to deal 
with products having the greatest portion 
performed in the U.S. I realize that many 
of the chips are made overseas, but with 
most of the tools I use the boards are de- 
signed, made, and stuffed here. In addition 
to supporting American products, I can 
talk to the developers if I need support. 

Some of the tools we use are as follows: 

8051 Cross-Assembler and Simulator 

-PseudoCorp, 716 Thimble Shoals Blvd., 
Suite E, Newport News, VA 23606, Phone 
(804) 873-1947 (see their ad in this issue). 
Dave Akey has a broad line of macro 
cross-assemblers, simulators, and cross- 
disassemblers which all run on an IBM 
PC. His products were recommended to 
me by Tim McDonough from Cottage Re- 
sources, and they work very well. 

8031 Development Board/uController 
Module— Cottage Resources Corpora- 
tion, Suite 3-672, 1405 Stevenson Drive, 
Springfield, IL 62703, Phone (217) 529- 



7679. Tim McDonough (see his article and 
ad in this issue) has developed these 
boards as a result of what he would liked 
to have had while developing embedded 
applications. These were designed to fill a 
need, by someone who was working in the 
area — not something designed by a com- 
mittee! I'm working with the Control-R I 
board which is a bargain at only $39.95. 1 
had been trying to get something going us- 
ing a solderless breadboard, but it didn't 
work because of poor connections. Now, 
with the Control-R I, I can concentrate on 
the application instead of fighting with the 
breadboard problems. Highly recom- 
mended for experimenting, prototyping, 
and the core for small quantity applica- 
tions. 

EPROM PROGRAMMER - 

Needham's Electronics, 4535 Orange 
Grove Ave., Sacramento, CA 95841, 
Phone (916) 924-8037. Alan Needham 
produces a quality product at a very rea- 
sonable price (see their ad in this issue). I 
am using the PC internal card version, but 
they also have stand-alone versions for 
production use. It automatically sets pro- 
gramming voltage, uses intelligent pro- 
gramming algorithm, and can split the 
bytes by two or four for 16 and 32 bit sys- 
tems. I have heard many horror stories 
about the overseas card bases program- 
mers, but Needham's is made in the US, is 
well made, and is well worth the $139.95. 

EPROM ERASER -Ultra Violet 
Products, Inc., 5100 Walnut Grove Ave., 
San Gabriel, CA 91778. Their DE-4 eight 
chip eraser (available direct or from 
Jameco for $69.95) has an intensity of 
6800 uW/square cm. It is well built and a 
good choice for mid-level use. They also 
have larger units for production use. 

BAR CODE READER -Adaptive 
Technologies, 810-208 Los Vallecitos, San 
Marcos, CA 92069, Phone (619) 744- 
8087. Douglas Johnson has just released 
his FlexScan I decoder, which includes a 
PC card, wand, and software. It can be ac- 
cessed as either a keyboard wedge, or 
driven directly thru the API (Application 
Program Interface). We are basing a bar 
code tutorial on this product. You'll see a 
lot more bar code applications, and you 
should start becoming familiar with the 
technology. Send for their literature. 

(Continued on page 35) 
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8031 ^Controller 
Modules 



NEW!!! 

Control-R II 

V Industry Standard 8-bit 8031 CPU 

V 128 bytes RAM / 8 K of EPROM 

V Socket for 8 Kbytes of Static RAM 

V 1 1.0592 MHz Operation 

V 14/16 bits of parallel I/O plus 
access to address, data and control 
signals on standard headers. 

V MAX232 Serial I/O (optional) 

V +5 volt single supply operation 

V Compact 3.50" x 4.5" size 

V Assembled & Tested, not a kit 

$64.95 each 



Control-R I 

V Industry Standard 8-bit 8031 CPU 

V 128 bytes RAM / 8K EPROM 

V 1 1.0592 MHz Operation 

V 14/16 bits of parallel I/O 

V MAX232 Serial I/O (optional) 

V +5 volt single supply operation 

V Compact 2.75" x 4.00" size 

\ Assembled & Tested, not a kit 

$39.95 each 



Options: 

• MAX232 I.C. ($6.95ea.) 

• 6264 8K SRAM ($10.00ea.) 

Development Software: 

• PseudoSam 51 Software ($50.00) 
Level II MSDOS cross-assembler. 
Assemble 8031 code with a PC. 

• PseudoMax 51 Software ($100.00) 
MSDOS cross-simulator. Test and 
debug 8031 code on your PC! 



Ordering Information: 

Check or Money Orders accepted. All 
orders add $3.00 S&H in Continental US 
or $6.00 for Alaska, Hawaii and Canada. 
Illinois residents must add 6.25% tax. 



Cottage Resources Corporation 

Suite 3-672, 1405 Stevenson Drive 

Springfield, Illinois 62703 

(217) 529-7679 



> 



Letters 



Z80 Controllers 

Your letter on small controllers was 
quite timely. A fellow hacker and I had 
been discussing (arguing) this very subject. 
He maintains that the (IBM) PC has made 
8 bit systems obsolete. The world is now 
standardized, and all computing in the fu- 
ture will be done with PC-compatible 
architectures. 

I pointed out that the vast majority of 
micros sold are 4- and 8-bitters. His PC 
had one 16-bit CPU, but half a dozen 8- 
bitters; in the keyboard, printer, modem, 
each disk drive, and in most other periph- 
erals. 

As to the future, RISC machines could 
be the death of the PC. They offer and 
order of magnitude more performance 
without the PC's ad hoc architecture and 
programming difficulties. It won't surprise 
me if RISC spawns a second micro revolu- 
tion. They'll replace today's micros as thor- 
oughly as they in turn replaced yesterday's 
minis. 

Imagine a 1995 Timex/Sinclair II, with 
it's RISC CPU and a meg of memory bit- 
banging video and disk I/O while emulat- 
ing any of a dozen CPUs... 

I am a good hardware engineer, and 
have several very small Z80 systems in my 
portfolio. It takes very little effort to put 
together powerful, inexpensive systems. 
I'm inclined toward a Z80 with 32K RAM, 
32K EPROM, and two 5380s for I/O. Ma- 
terial cost would be around $30. 

One danger is creeping featurism. Why 
not a 64180? 512 K RAM. Disk interface. 
Fancy video. Next thing you know, it's still 
another do-all computer, competing with 
the PC. No, I thing it should be a KISS 
design. If you want more horsepower, add 
more boards, or buy a PC. 

Why 5380s? For one, they have real- 
world drive capability. 8255s are cheaper, 
but need extra drivers to run anything real 
(LEDs, power transistors, relays, etc.). 
Second, they make fast inter-processor bus 
(SCSI) easy to implement. Why two 
5380s? Because 18 I/O lines is pretty 
skimpy for most applications. If more than 
36 lines of I/O is needed, add another 
board. 



Software is the hardest part. If we de- 
pend on assembly language programming, 
it will be inaccessible to most people. If we 
embed a high-level language, it is sure to 
offend the purists. BASIC? Forth? C? All 
of them have hate groups that won't use 
them, and none are suitable for multi- 
processor systems. 

I'd like to see something Smalltalk-like, 
sort of a "tiny-Talk." Each board is intelli- 
gent in its own right, and can be pro- 
grammed in a high-level language. In a 
multi-board system, they pass messages 
between each other (the user/programmer 
is just one more source/sink for messages). 
Smalltalk is the only language I know that 
has a structure for non-proceedural non- 
hierarchical processing. 

As a programming metaphor, I'm 
thinking of a spreadsheet. Each cell is an 1/ 

port or RAM location. You FORMAT 
the cell to determine how it inputs or out- 
puts data (serial, parallel, individual bits, 
etc.). The FORMULA is a one-liner in a 
calculator-like language. 

For Example, format cell Al as an 8-bit 
output, and Bl as an 8-bit input. The pro- 
gram in Al can do some boolean manipu- 
lation, like Al=(Bl+5)/2. If row A is 
physically handled by one board, it con- 
tinuously recalculates the output for Al, 
which involves sending a message to the 
row B board to ask the current value of 
Bl. 

So I'm interested! How do you suggest 
we proceed? 

Lee A Hart 

PC Development System 

Lee Hart sent me a copy of his May 
16th letter to you on small systems devel- 
opment and encouraged me to respond as 
the "fellow hacker...who maintains that the 
(IBM) PC has made 8-bit systems obso- 
lete". Well... 

I'm a good hardware engineer too, and 

1 find it hard to develop and manufacture 
a system as cheap as an IBM PC. For $500 
new, and maybe $250-$400 used, you get a 
2-floppy monochrome system. Admittedly, 

(Continued on page 36) 
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Embedded Systems for the Tenderfoot 

Getting Started with the 8031 

by Tim McDonough, Cottage Resources Corp. 



How many times have you had a great idea for a project that 
required some "smarts" but were put off by either the cost or the 
size of dedicating a PC to controlling the system? Or maybe your 
latest brainstorm required battery operation to be genuinely useful 
or your users just wouldn't tolerate keyboards, disk drives, etc. 
Learning how to develop stand alone microprocessor based proj- 
ects, or embedded systems as they are called in the trade, may be 
just the ticket to getting that project off the shelf and into the real 
world. 

Throughout the next couple of issues, or for however long Art 
is willing to put up with me, I'm going to present a few projects 
that will give you the basics of embedding a microprocessor in your 
projects. 

This isn't the kind of stuff that only rocket scientists and black 
belt computer hackers can succeed at. If you can already do some 
programming in BASIC, Pascal, C, or whatever and have some 
rudimentary knowledge of digital electronics, then getting started 
with embedded systems is within your reach. You probably won't 
have NASA beating down your door to work on the next genera- 
tion of space shuttles, but you will be able to develop some decent 
automation projects that do the job you need to accomplish. 

There are a variety of processors suitable for use in embedded 
systems. Z80s, 80286s, 68000s, and almost any other type you can 
think of are used in a variety of systems. The particular chip that 
I'll be concentrating on is the 8031 which is manufactured by Intel 
and second sourced by several other manufacturers. The 8031 is a 
member of what Intel calls the MCS-51 family. All members of 
this family have similar characteristics and a varying number of 
features and functions depending on your particular needs. Key 
features of the 8031, the "bare bones" model are as follows: 

• 128 bytes of internal RAM 

• Built in UART for serial communications 

• 2 16-bit counter/timers 

• 4 8-bit Input/Output ports 

• 2 external hardware interrupt lines 

• bit addressable memory and I/O ports 

Before I go on, let me say that the 8031 is not the only 8- bit 
microcontroller around; there are similar products made by Mo- 
torola and others. In any given group of engineers, scientists, or 

Tim McDonough is the President of Cottage Resources Corpora- 
tion. The company manufactures and distributes several single 
board computers based on the 8031 and is a dealer for PseudoCorp 
brand 8031 cross-assemblers and cross-simulators. He may be con- 
tacted at: Cottage Resources Corporation, Suite 3-672, 1405 Steven- 
son Drive, Springfield, Illinois 62703, (217) 529- 7679. 



programmers, you can get into discussions akin to religion or poli- 
tics if you say something like "The 8031 is the best 8-bit microcon- 
troller on earth." Fact of the matter is, the "best" is the one that 
you are the most comfortable using that will get the job done. I 
happen to have had access to a lot of people and resources that 
supported the 8031 while I was a "tenderfoot" and so I continue 
to use what I know best. 

The circuit shown in Figure 1 is a real bare-bones 8031 system. 
It contains the 8031, an address latch (more later), and 8K of 
EPROM to hold your application program, data tables, etc. This 
circuit is very similar to one presented by Steve Ciarcia in his Cir- 
cuit Cellar column that appeared in the August 1988 issue of 
BYTE magazine. 

You may wonder about the lack of RAM in the schematic. The 
applications I'll be presenting are written in 100% assembly lan- 
guage and since this gives total control of the system operation, the 
128 bytes of internal RAM contained in the 8031 will be more 
than adequate. 

Before we delve into the first application, there are a few "tools 
of the trade" that are required aside from the circuit shown in 
Figure 1. Whether you buy an off the shelf 8031 board or hand 
wire your own you will need the following minimum items to get 
into developing your embedded system: 

• The Intel 8-bit Microcontroller Handbook 

• A host computer on which to write software 

• A cross-assembler to produce 8031 object code 

• An EPROM programmer to get your object code into a 

blank EPROM. 

• An EPROM eraser to get rid of your inevitable mistakes. 

The amount of money you'll spend on these items can vary. 
There is no upper limit to price but a workable system such as the 
one I typically use at home will cost about $270.00. This includes a 
cross-assembler, EPROM programmer, and an EPROM eraser. 
If you build up a simple 8031 circuit of your own and purchase a 
few EPROMs for experimenting, you can still get started for about 
$300.00. 

So much for the introduction. This first project will get you 
used to how some of the more useful pieces fit together and pro- 
vide you with a working code example that you can use as the basis 
for your first experiments. It demonstrates how to read digital 
input sources such as switches, photocells, etc. and shows how to 
control simple digital output devices such as relays, LEDS, and 
small motors. 

Before jumping into the project itself, a quick tour of the 
"computer" is in order. As shown in Figure 1, the system is com- 
posed of 3 Integrated Circuits-an 8031, a 74LS373 address latch, 
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and a 2764 EPROM. 

The 8031 is essentially the entire computer. It contains RAM, 
several counter/timers, system clock circuitry, and a full- duplex 
UART that can be used to implement a serial communications 
port. The 2764A is an 8K EPROM that is used to hold the pro- 
gram that the 8031 will execute. A 74LS373 is used as a "glue" 
chip to hold the other parts together. The 8031 design multiplexes 
the low order address lines (A0-A7) onto the same 8 lines as the 
data (D0-D7). A separate external Address Latch Enable (ALE) 
line (Pin 30) is used to latch the lower byte of the 16-bit address 
into the 74LS373, after which the bus is used for data transfer. 

The purpose of the system described here is of little interest; 
it's the implementation that should pique your interest. Essentially 
it is a complicated, but flexible equivalent of an exclusive "or" 
(XOR) logic gate. That is, whenever one and only one of the 
inputs is active (grounded), the LED will light. Any other input 
conditions will cause the LED to remain off as shown in the fol- 
lowing truth table: 

TRUTH TABLE FOR A TWO INPUT "XOR" GATE 

INPUT A (P1.0) | INPUT B (Pl.l) | OUTPUT (PI. 2) 

+ + 

HI | HI | HI 
+ + 

HI | LOW | LOW 

+ + 

LOW | HI | LOW 
+ + 

LOW | LOW | HI 

HI == +5VDC, LOW = OVDC/GND 

This software "gate" could of course be a part of a much larger 
system and in fact I'll be expanding on it in the next several issues. 



For now, making it work will give you a good opportunity to get 
comfortable with the basic 8031 circuit, cross-assembler, and 
EPROM programmer. The test circuit is shown in Figure 1. 
Switches A and B let you simulate the inputs to the "gate" and 
LED #1 will let you track the output. 

Remember I mentioned earlier that a lot of things don't re- 
quire much in the way of memory? The code for the exclusive-OR 
gate uses none of the 803 l's RAM and only occupies 19 bytes of 
the system's 8K EPROM. The source code is shown in Listing 1. 

Coding in assembly language, although at times a bit more tedi- 
ous, is no different than using whatever high level language you're 
using now. In the case of implementing the exclusive-OR gate in 
software I simply check each possible set of conditions one by one. 
The algorithm, in pseudo code, is as follows: 

"main" 

if SW1 is set then 

goto "check SW2" 
if SW2 is set then 

goto "turn LED on" 
goto "turn LED off" 

"check SW2" 
if SW2 is clear then 
goto "turn LED on" 

"turn LED off" 
clear LED1 
goto "main" 

"turn LED on" 

set LED1 
goto "main" 



The actual assembly language source code isn't quite as lucid as 











LISTING #1 - Embedded Systems for the Tenderfoot 


000001 


0000 




XOR. ASM 


— May 


9, 1990 


000002 


0000 










000003 


0000 




(C) Copyright 1990 by Tim McDonough 


000004 


0000 




Cottage 


Resources Corporation 


000005 


0000 




Suite 3 


-672, 1405 Stevenson Drive 


000006 


0000 




Springf 


ield, Illinois 62703 


000007 


0000 




(217) 529 - 7679 


000008 


0000 










000009 


0000 






.ORG 


H'0000 ; ASSEMBLE TO BEGIN AT 0000 HEX 


000010 


0000 










000011 


0000 




EQUATES 


are used to give memory locations, registers and bits somewhat 


000012 


0000 




english 


-like names 


000013 


0000 










000014 


0090 






.EQU 


SW1,P1.0 ; SWITCH #1 ON PORT 1, BIT 


000015 


0091 






.EQU 


SW2,P1.1 ;SWITCH #2 ON PORT 1, BIT 1 


000016 


0092 






.EQU 


LED, PI. 2 ;LED #1 ON PORT 1, BIT 2 


000017 


0000 










000018 


0000 




• The main program is an endless loop that constantly compares the status 


000019 


0000 




■ of the 


two input pins against the XOR truth table and adjusts the state 


000020 


0000 




• of the 


output pin accordingly. 


000021 


0000 










000022 


0000 


309005 


START: 


JNB 


SW1,S1_0 ;IF SI = CHECK S2 


000023 


0003 


309109 




JNB 


SW2,LED_ON ;S1 = 1 AND S2 = 


000024 


0006 


8003 




SJMP 


LED OFF ;S1 = 1 AND S2 = 1 


000025 


0008 










000026 


0008 


209104 


51_0: 


JB 


SW2,LED ON ;S1 = AND S2 = 1 


000027 


000B 










000028 


000B 


D2 92 ] 


LED_OFF: 


SETB 


LED 


000029 


000D 


80F1 




SJMP 


START 


000030 


000F 










000031 


000F 


C292 ] 


LED_ON: 


CLR 


LED 


000032 


0011 


80ED 




SJMP 


START 


000033 


0013 






.END 
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the pseudo code. "XOR.ASM" is shown in Listing 1. The file is 
formatted for the PseudoSam 51 Symbolic Assembler (See the 
notes at the end of the article for details). 

When the 8031 is first powered up, it starts trying to execute 
instructions found at location 0000 Hexadecimal. The .ORG di- 
rective tells the assembler to locate the assembled instructions be- 
ginning at 0000 Hexadecimal as well. Next an "equate" directive is 
used to assign some "reader friendly" names to several of the 
8031's I/O pins. The first equate assigns the symbol "SW1" to Port 
1, Bit (P1.0), the location were I've attached Switch #1. 

A major advantage of the 8031 for control applications is its 
ability to manipulate single bits as opposed to performing opera- 
tions on only full bytes. The JNB instruction looks at the bit refer- 
enced in the first argument and causes program execution to jump 
to the label referenced in the second argument if the bit was not 
set. If the bit was set, nothing happens and the next instruction is 
executed. The JB instruction does just the opposite, jumping if the 
referenced bit is set. 

The other instructions used are fairly straight forward. SETB 
and CLR set and clear bits, respectively. SJMP is practically like a 
GOTO in BASIC or FORTRAN. It simply forces program execu- 
tion to continue to a certain location. 

I hope it's obvious that using a microprocessor, EPROM, latch, 
crystal and all the other assorted components in this project as a 
replacement for an XOR gate isn't a great idea in and of itself. If 
all you need is a gate then by all means use one. But what if we 
wanted to transmit the status of the two switches to a PC via a 
serial port? What if we needed to measure a temperature in addi- 
tion to knowing the two switch positions? To accomplish either of 



these tasks and many more, very little additional hardware is 
needed. It's mostly "code". 

If you decide to experiment more with the 8031, the basic cir- 
cuit described in this article can be used over and over for a variety 
of projects. Some people will want to wire-wrap or point to point 
wire their own board to make it exactly what they want. If you 
don't have the time to build or would rather spend the bulk of 
your time coding, an assembled and tested version of this circuit 
that also includes the circuitry for an RS232 compatible serial port 
(I'll be talking about serial port programming in an upcoming is- 
sue) is available from Cottage Resources Corporation. The Con- 
trol-R I (pronounced "Controller One") is available for $39.95 
and the PseudoSam 51 cross-assembler is available for $50.00 
(plus $3.00 Shipping per order) from Cottage Resources Corpora- 
tion, Suite 3-672, 1405 Stevenson Drive, Springfield, Illinois 62703, 
(217) 529-7679* 

References: 

Embedded Controller Handbook, Volume I 8-bit 1988, Intel 
Corporation. 

Mastering Digital Device Control by William Houghton, 1987, 
SYBEX. (Editor's Note: This book is out of print.) 

Why Microcontrollers? Part I, by Steve Ciarcia, August 1988, 
BYTE Magazine. 
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The Z-System Corner 

by Jay Sage 



Last time we gave you a pretty thorough presentation of the 
script language from the MEX-Plus telecommunications program. 
However, as necessary as such documentation is, it does not really 
teach one how to make effective use of the language. So this time 
we will present as a teaching example significant portions of the 
script suite that I use for almost all my telecommunication work. It 
is the most complex script that I have ever written, illustrates many 
techniques, and might be very useful to many of you as well. 

This script is far from perfect. Every time I work with MEX- 
Plus I learn something more about it, and that was a large part of 
my motivation for writing these two columns. As usual, I hope that 
some astute readers will notice ways to improve on my script. 

More MEX Commands 

Before getting into the script itself, I have a few items to add to 
the discussion from last time. First, I forgot to mention one ex- 
tremely important MEX command; second, just today I discov- 
ered some more undocumented commands that appear to be 
quite interesting. 

The WAIT Command 

The WAIT command is one of MEX's most important com- 
mands. It allows MEX to monitor the character stream coming 
back from the remote system and to take various actions depend- 
ing on what it sees. There are four variants of the command: 
WAIT DATE, WAIT TIME, WAIT SILENCE, and WAIT 
STRING. 

The first two forms cause the script to pause until a specified 
date or time arrives. Obviously, you must have a real-time clock 
and a MEX clock module installed for these commands to work. 
The command forms are: 



WAIT DATE nm/dd 
WAIT TIME hh:mm 



These commands would be useful for a script to automatically 

Jay Sage has been an avid ZCPR proponent since the very first 
version appeared. He is best known as the author of the latest ver- 
sions 3.3 and 3.4 of the ZCPR3 command processor and for his 
ARUNZ alias processor and ZFILER point-and-shoot shelL 

When Echelon announced its plan to set up a network of remote 
access computer systems to support ZCPR3, Jay volunteered imme- 
diately. He has been running Z-Node #3 for more than five years 
and can be reached there electronically at 617-965-7259 (MABOS 
on PC-Pursuit, pw=DDT). He can also be reached by voice at 61 7- 
965-3552 (between 11pm and midnight is a good time to find him at 
home) or by mail at 1435 Centre St., Newton, MA 02159. Jay is now 
also the Z-System sysopfor the GEnie CP/M Roundtable and can 
be contacted as JAY.SAGE via GEnie mail or chatted with live at 
the Wednesday real-time conferences (10pm Eastern time). 

In real life, Jay is a physicist at MIT, where he tries to invent 
devices and circuits that use analog computation to solve problems 
in signal, image, and information processing. His recent interests 
include artificial neural networks and superconducting electronics. 
He can be reached at work via Internet as 
SAGE@LL.LL.MIT.EDU. 



place a call during the middle of the night when phone rates are 
lower. 

The WAIT SILENCE command waits until no characters have 
been received from the modem for a specified time interval. This 
is one way to infer that the remote system has finished what it was 
doing and is ready for a command from you. The syntax is: 

WAIT SILENCE [time] 

The most powerful of the WAIT commands is WAIT 
STRING, whose full syntax is: 

WAIT STRING [time] atringl [ string2 0tring3 Btring4 ] 

This command takes from one to four string expressions and 
an optional wait time, which otherwise defaults to values set by 
STAT parameters. The command terminates as soon as one of the 
strings is detected or the time limit expires. The VALUE variable 
tells you the result. It will be if the time limit was reached or 1, 2, 
3, or 4 depending on which string was matched. You will see a 
number of examples of the use of this command in my PC-Pursuit 
script. 

Undocumented Commands 

MEX has quite a number of undocumented commands. These 
can be discovered by doing a memory dump of MEX.COM and 
looking for the command dispatch table. Scanning programs' com- 
mand tables to see what goodies might have been built into them 
that the authors — for one reason or another— decided not to tell 
you about is a great sport. I will mention only a few of the MEX 
commands I discovered this way. 

First, there are some commands that are just alternate names 
for documented functions. For example, there is a RENAME 
command that vectors to the same code that the REN command 
does. 

Since, as I mentioned last time, there seemed to be a paucity of 
ways to get out of MEX (only about six commands!), I was quite 
relieved to discover the command ABORTMEX, which appears 
to offer yet another way! Actually, I have a recollection of having 
seen that command somewhere in the documentation, but it is not 
listed in the index and I cannot find it again. From examining the 
dispatch vectors, I can tell that ABORTMEX is not the same 
thing as CPM, EXIT, QUIT, and so on, but it seems to do the 
same thing. 

One command that I think will prove quite useful is the 
PAUSE command. Its syntax appears to be like that of the un- 
documented PRINT. Whatever text comes after it is echoed to 
the screen, and the script then pauses until any key is pressed. 

The MEM command looked as though it was going to be quite 
useful, as it displays the status of MEX's memory buffer. The 
trouble is, I have not been able to figure out what buffer this is! I 
started a capture buffer, and MEM still showed the same values 
and reported that none of the buffer was in use. Then I put the 
command in a script file, thinking it might report the status of the 
script buffer. Alas, the report was still the same. Perhaps this is just 
a command that was never fully coded. All I can say is that the 
buffer size reported does depend on the size of one's TPA. 
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Another very interesting command is WIN. Its name suggested 
that it created some kind of window, and indeed it does. It is proba- 
bly not documented because it does not seem to work completely 
correctly. I entered the command 



WIN 5 5 12 75 



and MEX drew a partial box of the sort that "BOX 5 5 12 75" 
would have and then put its prompt at the upper left corner of the 
window. After that, screen output was restricted to the lines in the 
window, but the lateral limits of the window were not observed; text 
still ran across the full width of the screen. The STAT command 
would fill just the window and then wait for a keypress to continue. 
Of course, I did my tests from the command line, and WIN may act 
differently if invoked from a script file. 

The "@" command cursor addressing could still take one any- 
where on the screen. Thus, it looks as though the WIN command 
might be useful in some special cases where one wants to keep 
certain status information on the screen. The window could be set 
to the last 20 lines on the screen, and status information could be 
written using "@ SAY" to the regions outside the window. 

Another command whose function I thought I could guess was 
FLUSH. I assumed that it flushes the contents of a buffer, perhaps 
the capture buffer. However, I tried it with a capture buffer, and 
nothing seemed to happen. There must be something more subtle 
about it. 

Finally, there are the commands DUPE, RESTORE, TRAP, 
LIB, EXEC, OVRINIT and probably a few others. 

A Challenge 

I will offer an unspecified prize to the user who does some detec- 
tive work and sends me the most complete documentation on these 
undocumented commands. A free copy of the Mex-Pack terminal 
emulation and remote operation modules might be a fitting prize. 
Or perhaps a copy of the new ZMATE macro text editor. 

I also have some recollection that someone once figured out a 
way to use either the strings assigned to keys or the names in the 
phone directory as string variables. So far, however, I have not been 
able to figure out how to do it. We'll include that and any other 
undocumented information about MEX-Plus within the framework 
of this challenge. 

Now let's begin the look at the PCP script. 
The PC-Pursuit Script 

The Purpose 

The purpose of this suite of MEX scripts is to make life with PC- 
Pursuit easier. Before the recent changes in policy, using PCP was 
an enormously frustrating experience. The outdial modems were 
almost always busy, and it sometimes took dozens or even hundreds 
of tries to get connected to a desired city— each try requiring one to 
enter one's user ID and password. Today, with the 30-hour limit on 
free access, things are much, much better, but it is still handy to 
have a script take care of the operation automatically. 

Here is basically what my script does. It calls up the local Telenet 
access point and issues the commands to set up the proper terminal 
mode. Then it negotiates a connection to the city where the selected 
remote access system (RAS) is located. If all the modems in that 
city are busy, the script can keep trying. If all the 2400 bps modems 
are busy, it can even automatically step down and try the 1200 bps 
modems. Today, one rarely fails to connect on the first try at 2400, 
but in the past the multiple tries and automatic stepdown were 
lifesavers. 

Once the connection to the city has been established, the script 
issues the commands to put the remote modem into Racal Vadic 
mode and then dials the number for the RAS. In Vadic mode, the 
modem issues call status reports, so you know when the modem is 
dialing, when the phone is ringing, when the line is busy, and when 
the call has simply failed. The MEX script monitors these reports 
and responds appropriately. 

Once the remote system has been reached, a very short script is 



initiated so that a maximum amount of memory will be free for 
MEX to use for its capture and file transfer buffers. The script also 
programs several function keys to make logging onto the RAS eas- 
ier. 

It would be quite easy to have the PCP script chain to a script to 
perform the complete login operation, but I generally prefer to do 
this manually. That gives me a chance to notice if there are any new 
bulletins or other changes in the system. 

Design Philosophy 

Two main principles guided the design of the script suite. First, 
as I mentioned last time, I made it highly modular. This makes 
writing the script easier and clearer but, more importantly, it over- 
comes memory limitations. By chaining from one script to another, 
only one script has to be in memory at one time. By making the last 
script a very small one, almost no buffer space is lost during the 
time the user is working on the remote system, even though a script 
is still in operation. 

The second principle is to provide as much error checking as 
possible. For example, at the very beginning, the script checks to 
make sure that the local modem is connected, turned on, and re- 
sponding. I learned to do this after trying many times to run this and 
other scripts with the modem turned off. 

In its present form, when an error is detected, the script nor- 
mally issues an explanatory message and then terminates. It would 
be better to provide error recovery wherever possible. For example, 
having discovered the PAUSE command, I might now improve the 
script by making it pause until the user turns the modem on and 
presses a key. Then the script would loop back and try again. 

There are quite a few places in the script where it will retry a 
failed operation several times before it gives up. Sometimes PC- 
Pursuit just seems to go out to lunch, and I have been unable to get 
any response from it even with manually entered commands. In 
such cases, of course, there is nothing more that the script can do. 

Architecture 

Before talking about the detailed functions of each module in 
the script, I would like to describe the architecture. There are 6 
modules, and their relationships are shown in Figure 1. 

The central script is in the file PCPMENU.MEX. The invoca- 
tion script, PCP.MEX, performs some one-time operations and 
then transfers control to PCPMENU. After that, control branches 
to other scripts but eventually returns to the menu script. It is only 
from PCPMENU that the script can be terminated and control 
returned to CP/M in a graceful fashion. 

The data needed to connect to a remote system can be supplied 
in two ways. First, the menu displayed by PCPMENU lists many 
commonly called systems. When one of these is selected, control 
branches to PCPDATA, which loads the required data into MEX 
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Figure 1 . This shows the architectural organization of the suite 
of script files that comprise the complete PCP script. 
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numerical and string variables and function keys. 

Alternatively, there is a choice for contacting a RAS that is not 
on the menu. In this case, the script PCPMAN (short for 
PCPMANUAL) provides for step-by-step, menu-driven entry of 
the required information. If the user decides against making that 
call, control can be returned to PCPMENU. Normally, however, 
control from either PCPDATA or PCPMAN flows to PCPCALL. 

PCPCALL carries out the operations required to make PC- 
Pursuit connect to the requested city and then dial the requested 
• local telephone number. When either the PCP or RAS modems is 
busy, the script allows the user to decide whether to continue 
trying and how many times. If the call cannot be completed and 
the user does not want to continue trying, control returns to 
PCPMENU. 

If the remote system is reached, control is passed to the small 
script PCPCONN (short for PCPCONNECTED). We showed 
this script in the previous column. It puts the user into terminal 
mode for login. Whenever the user exits back to MEX command 
mode, a prompt is put up. Entering the command "M" returns 
control to PCPMENU. Other MEX commands can be entered as 
usual for transferring files, opening capture buffers, changing 
STAT parameters, and so on. 

This script suite does not make use of any subroutine scripts 
invoked using the DO command. In all cases, control is transferred 
permanently to another script using the READ command. There 
are some subroutine command blocks defined by the PROC and 
ENDP commands. These subroutines are contained within the 
script file because they execute faster that way and because there 
was no reason in most cases to implement them as separate files. 

We will now make a few comments about details of the individ- 
ual script files. Because the code is quite lengthy, we are unable to 
print it all here. Many whole sections have been removed, and 
some comments have been cut out. However, there are several 
ways to obtain the complete scripts. First, they will probably be 
included on the ZSUS (Z-System Software Update Service) sub- 
scription disk that is released at about the time this issue appears. 
Second, the files will be posted on RASs. Finally, Art Carlson has 
offered to make them available to subscribers who send him a 
formatted, labeled diskette with return postage and mailer. 

Script PCP.MEX 

This script (Listing 1) initializes a number of variables. Note 
that variables that the user is likely to want to change are placed at 
the beginning of the script. Also note that certain values that could 
have been hard coded into the script, such as the default number 
of tries to connect to a city, are stored instead in numerical vari- 
ables. This is like using EQU parameters in assembly code and is a 
highly recommended practice. It is not a bad maxim never to use 
actual numerical constants in any program; always use symbolic 
constants. 

Table 1 shows how variables are used in the scripts. I'll have to 
confess that I prepared much of this list after the fact. That was a 
mistake. I would have made many fewer coding errors had I me- 
ticulously documented the use of variables from the very begin- 
ning. In fact, the comments next to each variable should be more 
extensive than what I show here. Some of the information is in- 
complete; some may even be wrong. 

Note the way command line parameters are handled in 
PCP.MEX. The full syntax for invocation of the script is 

READ PCP (mbu choics] [city tries] [RAS tries] 

There are three optional parameters. The first is a menu 
choice. If you know that you want to place a call to RAS number 1 
on the menu, you can use the command "READ PCP 1" to do so 
directly. In case you think that it is too hard to remember the 
numbers, you are right; that's where ARUNZ aliases come in! My 
LADERA alias becomes "MEX READ PCP 1". The other two 
parameters are the default number of times to connect to a city's 



outdial modem and the destination modem, respectively. 

The parameter values are carefully validated in the script. If the 
values are illegal, then the built-in defaults are used. Validating 
user input is something that none of us does enough of. 

In the part of the script that checks the local modem, there is 
the command 



WAIT STRING 2 "OK- 



This makes the script wait for up to 2 seconds for the modem 
to respond with either "OK" (which it will do in normal verbose 
mode) or "0" (which it will do if it was left in terse mode). It is 
always a good idea to have code anticipate and deal with all pos- 
sible situations. 

I have an MNP level-4 modem, and Telenet supports MNP 
error correction at the indial port that I use. Therefore, I put the 
modem into MNP mode at the beginning of the PCP script and 
set it back to normal mode on normal exit. I have omitted this 
code from the listing. If you do not have an MNP modem, you 
would, of course, remove (comment out) this part of the script. 

The script is pretty carefully written to make sure that every- 
thing is proceeding correctly. After connecting to Telenet, up to 
two attempts are made to establish the required synchronization. 
This same technique of looping with a max-tries count in variable 
%z is used in many places throughout the scripts. Note the use of 
the SLEEP command to introduce delays when the system you are 
communicating with does not always respond immediately. 

Script PCPMENU.MEX 

The menu in this script (Listing 2) is drawn inside a box and has 
the RAS selections displayed in three columns. Free entries are 
filled in with a row of dots. We have included only enough entries 
to show how they are generated. It is important that free entries be 
trapped later in the script. 

The menu is adaptive. If one is currently connected to a city, 
the city code and data rate are shown in the menu header, and the 
menu selections for changing the data rate that otherwise appear 
at the bottom are omitted. 

Another example of robust coding is provided by the ABORT 
routine at the end. Whenever this script is running, we should be 
connected to PC-Pursuit. Therefore, the script attempts to discon- 
nect by sending the HANGUP command that PCP likes to see. If 
several attempts to disconnect in this way fail, however, we simply 
drop carrier. 

Script PCPDATA.MEX 

This script (Listing 3) is quite straightforward. It sets some de- 
fault key definitions that apply to many systems. Then it branches 
to the entry for the RAS selected from the menu in PCPMENU. 
Here the variables necessary to place the call are set and any other 
function key definitions are made. Then control is transferred to 
PCPCALL. In the listing we show the entry for only one RAS. 

Script PCPMAN.MEX 

This is the second most complex module in the series (Listing 
4). I used to have a much simpler and less agreeable version; in 
honor of this column I just rewrote it. It used to require manual 
entry of all information, and it provided no checking. Now it puts 
up a menu of all PCP cities and allows selection by number. It also 
keeps track of the area codes covered by each city. When there is a 
second area code, a menu lets the user choose. The script is even 
smart enough to include the area code as part of the local number 
when needed and to insert the "1" prefix for those phone systems 
that require it. 

There are two major subroutines in this module. Routine CI- 
TYNAME takes the city number and produces the name of the 
city and state in a string variable. Routine PCPCODE generates 
the PCP outdial code and the telephone area codes for the city. 
The same CITYNAME subroutine is also included in module 
PCPCALL. 
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Listing 1 : Script PCP.MEX. 



.. PCP.MEX: MAIN PCP SCRIPT (04/15/90) 

. . This ie the main entry point to the script for automating 

.. calls via the PC-Pursuit network. This part of the script 

. . handles initialization of HEX and the modem and establishes 

.. the connection to the local access number. 

. . Two things we have to take care of right away 

screen off 
stat sep " ; " 



Configuration Information 



stat filter on 
stat trigger ""; 
stat sodelay on; 
stat reply 0; . 
stat case on; . 
. . etc . 



turn filter on 

do sendouts immediately 

..but at a slow rate 

do not wait for response to a sendout 

ignore case 




.. Hake sure the modem is connected and responding. 

sendout "AT/r" 

wait string 2 "OK - "0";. allow verbose or terse responses 

if value-0 A-*"No response from local modem"; GOTO ABORT 

.. etc. 



phone pcp"000-0000 2400; 
A»"Your Town -Class B"; . 
key i-"PCP_USERID";. 
key w""PCP__PV; . 

%m-100;. 

%t«5; . 

%s«l;. 

%b-2400;. 

B— 24" 

%n-2 ; . 

key 0«"read pcpmenu/r"; 



local access number and baud rate 
type of Telenet access for msg later 
key for entering user ID 
key for entering password 

default menu (100 -> display it) 
default attempts to reach city 
default attempts to reach BBS 
default baud rate value for outdial 
default baud rate as a string 
automatic stepdown mode 
key for reinvoking script 




tell user what we are doing 



Initialization 



.. Initialize data from command line. There are three optional 

.. parameters. The first is a menu selection number to call 

.. immediately. The second is the number of attempts that 

.. should be made to connect to the destination city. The third 

. . is the number of times to attempt to connect to the local 

.. number in that city. In all cases, we check to make sure that 

.. we have an acceptable value. 



menu selection (variable %m) 



%d-{l:0};. 

if %d<l GOTO BAD1;. 

if %d>100 GOTO BAD1 

%»-%d; . 

LABEL BAD1 



read parameter 1 with default value of 
ignore if illegal value 

if value in range 1..100, use it 



screen on; . 

say "/n/nDialing Telenet (",A,") 

screen off 

. . place call to Telenet 

dial pep 

if value -0 A-"No connection to Telenet: ";GOTO ABORT 

screen on 

say "CONNECTED/n" 

. . initialize PCP session 

%z«2;. max tries 

LABEL LOGIN 

if %z<l A""Telenet not responding";GOTO ABORT 

%z-%z-l 

screen on; say ■ sync... ";screen off 

sendout "G";aleep 1; sendout "D/r" 

wait string 1 "TERMINAL" 

if value-0 sleep l;goto LOGIN 

screen on; say "terminal ID... "; screen off 

sendout "Dl/r" 



read PCPHENU; . 



chain to PCPMENU script 



.. similar code for other parameters omitted. 

.. Initialize various variables and MEX parameters 

ta-0;. no area code requested 

. . etc . 

D»" ";. no PCP outdial (city) code 

.. etc. 




LABEL ABORT 

screen on 

say "/n/n",A,"; session aborted. /n/n" 

dsc 



The menu of PCP cities is drawn by calling the CITYNAME 
routine from inside a loop. This is much slower than drawing the 
menu directly. I put the code for the CITYNAME subroutine at 
the beginning of the script, since I think it executes a little faster 
from there. 

I wrote the script this way for two reasons. First, it illustrates 
some interesting techniques, such as iterated loops and computed 
coordinates for the "@" command. Second, it keeps information 
about the city names in one place. If they are kept in more than 
one place, then when changes are made in the future they might 
not be made everywhere. As it is, this danger exists in several 
places in these scripts. For example, the menu of RASs is drawn in 
PCPMENU, but the data for each RAS are stored in PCPDATA 
When changes are made, the user must be sure to keep the infor- 
mation synchronized. 

Script PCPCALLMEX 

Now we come to the most complex module in the script (List- 
ing 5). This one has to perform a lot of housekeeping and tricky 
operations. It has to know if we are already connected to a city and 
if so which one. It then has to decide how to go about connecting 
to the requested city. This may require disconnecting from the 

(Text continued on page 15) 



Table 1 : A list showing how the string and numerical variables are 
used in the scripts. 

A error message string, temporary string 

B baud rate 

C temporary city code in PCPMAH 

D PCP outdial city code 

E RAS phone number 

F RAS system name, scratch sometimes 



%a 

%b 
%c 
»d 
%e 
%f 

*g 

%h 
ti 

*3 
%k 
%1 
tm 
>n 
to 

*P 

»q 

*r 
%s 
»t 

%u 
%v 
%w 
%x 

*y 

%z 



area code of city currently connected to (or if none) 

maximum baud rate 

current city selection (see PCPMAH. HEX menu) 

temporary variable 

max number of tries 

main area code 

alternate area code (or if none) 

flag for "1" prefix requirement (0 if not required) 



menu selection 

stepdown mode ( - manual, >0 * automatic ) 

flag used to indicate current stepdown status (0 - no 

. . stepdown yet ) 

number of city actually connected to 

count of number of rings detected 

default tries to connect to RAS 

default tries to connect to city 

flag to show intial attempt to connect to a city or RAS 

flag to show Vadic status ( >0 if modem in vadic mode ) 

cursor row 

loop index 

cursor column 

dummy counter 
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Listing 2: Script PCPMENU.MEX 



.. PCPMENU.MEX (04/15/90) 

if taKlOO GOTO PROCESS;. if selection already made, process it 



Main Re-entry Point and Display of BBS Menu 



LABEL DRAWSCREEN 

screen on 

els 

box 1 1 20 79 

* 2 32 say -PC-PURSUIT MENU" 

(63 say -1. Al Hawley (ZN02)- 
. . etc . 

■ 14 3 say -9. Vanhorn (ZN66)- 

t 6 27 say -10. Roger Warren (ZN09)" 
.-. etc. 

# 14 27 say "18 - 

■ 6 52 say "19. Terry Pinto" 

( 11 52 say "24 " 

.. etc. 

t 12 52 say "25 ■ 

( 14 52 say "27. WLA PCBoard" 

• 16 12 say " 0. RESET" 

* 17 12 say " 99. QUIT" 

t 18 12 say "100. MANUAL ENTRY MENU" 

. . The following baud-rate-selection choices are allowed only if 
.. not presently connected to a city. 

if %a-0 

• 16 45 say "200. 2400 BAUD AUTO" 

• 17 45 say "201. 1200 BAUD FIXED" 
€ 18 45 say "202. 2400 BAUD FIXED" 

endif 



Baud Rate / City Connection Status Display 



LABEL DRAWBAUD 

if %a«0 
if *n>0 

€ 4 20 say " Set to max ",%b," bps (auto stepdown) 
else 

* 4 20 say " Set to ",%b," bps 

endif 
else 

f 4 20 say "Connected to Citycode ",D," at ",B,"00 bps- 
endif 



Get / Process Selection 



LABEL GETSEL 

C 22 12 say "Enter Selection: 



• 22 29 

input ; %m-value 



LABEL PROCESS 



special selections 



if %m-0 GOTO RESET 

if %m-99 A-"User termination";GOTO ABORT 

if %m-100 READ PCPMAN; . manual entry of city and phone # 

• • if already connected to a city, do not allow baud rate changes 
. . by resetting the choice to 9999 

if %pO0 

if %m>-200 tm-9999 
endif 

. . handle baud mode selections 

if %m-200 %n-2;%b-2400;B-"24";GOTO DRAWBAUD 
if %m*201 ln-0;%b-1200;B-"12";GOTO DRAWBAUD 
if %m-202 %n-0;*b"2400:B-"24";GOTO DRAWBAUD 

if %m>27 GOTO BADSELECT 
if %m<l GOTO BADSELECT 

. . calling selections 

.. reject unassigned menu choices 

if %m-12 GOTO BADSELECT 

. . etc . 

if %m-25 GOTO BADSELECT 



READ PCPDATA; . 
LABEL BADSELECT 



bell 1 
GOTO GETSEL 



chain to data fetch routine 



significant part of script omitted 



Subroutines 



LABEL ABORT 

screen on 

els 

(50 say A, 

%z-3;. 



session ended." 



max tries 



LABEL ABORT1 

%I-%I-1 

if IK1 dsc;GOTO ABORT2;. 

screen on 

sendout -/r«/r";. 

wait string 1 "6" 

if valueol GOTO ABORT 1 

sendout "hangup/r" 

wait string 10 "NO CARRIER" 

if value <>1 GOTO ABORT1 



LABEL ABORT2 

sendout "AT\Nl/r" 

say "/n/nModem MNP mode turned off/n" 

cpa 



if soft disconnect fails, hang up 
send disconnect commands to Telenet 



Listing 3: Script PCPDATA.MEX 



PCPDATA. HEX (04/14/90)) 



This routine contains all the data for the systems in the 
menu. Each entry sets the following variables: 



. . dispatch table 
if tm-1 GOTO BBS01 

.. etc. 

if tm-27 GOTO BBS27 



E 
F 
%a 

%c 



actual baud rate code ("12" or "24") 

outdial code 

phone number 

name of system called 

area code 

city number (see PCPMAN menu) 



In addition, function keys are set up (where the defaults are 
not correct) with the login names and/or passwords. 



key l-"Your Name/r";. 
key 2-"Your-usual-pw/r" 

if %b-1200 B— 12" 
if %b-24 00 B— 24" 



default key definitions 



Data on Remote Access Systems from Menu 



LABEL BBS 01 

F-"Al Hawley (ZN2)" 

D«"CALAN" 

lc-13 

%a-213 

E—670-9465" 

key l«"###CCCCCCC/r" 

READ PCPCALL; . 



login id/password combination 
chain to place the call 



entries for other syste 
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Listing 4: Script PCPMAN.MEX 



PCPHAN.HEX (04/14/90) 



. . This subroutine script handles the manual entry of data for a 

. . destination RAS . 

.. See if there is usable call data already defined. If so, the 

.. user will be given the option of using it (in case this is a 

.. second attempt to make the same manual call). Otherwise, we 

.. will skip that menu and go directly to the data input menus. 

GOTO START 



Subroutines (placed at beginning for speed) 



. . This subroutine is passed the city number in scratch variable 
. . %d and returns the name of the city in string variable A. 

PROC CITYNAME 

if %d-l A—Atlanta, GA-;ENDP 

.. etc. 

if *d-34 A— Washington, DC";ENDP 

A—Unknown City" 

end; 



. . This subroutine takes the city number in %d and sets the PCP 

. . city code into string variable C , the main area code into 

.. variable %f, and any additional area code into %g. Variable 

.. %h is set to 1 if a "1" prefix is required. 

PROC PCPCODE 
. . initialize 



%f-0; . 
%g-0; . 
th-0; . 
C-" ";. 



no main area code 
no alternate area code 
no "1" prefix needed 
no city code 



if %d-l C— GAATL";*f-404;ENDP 

if %d-2 C--MABOS";%f-«17;ENDP 

if %d-3 C— ILCHI";%f-312;%g-S15;»h-l;r— 815";ENDP 

.. etc. 

if %d-29 C-"CASJO";%f-408;%g-415;r— 415";ENDP 

.. etc. 

if %d-34 C— DCWAS";%f-202 

ENDP 



LABEL START 

C-D; . set temporary city code to current value 

if %C-0 GOTO SETCITY 

comp C ■ ";if value-1 GOTO SETCITY 

comp E ■ -;if value-1 GOTO SETCITY 

screen on 



Ask About Entering New RAS Data 



%d-%c; . convert city code into city name in A 
GOSUB CITYNAME 



box 1 



',A 

",C 

",*b 



,%a 



5 15 50 

19 say 'Manual Call Entry" 

10 say "1. use current data" 

15 say "System Name: 

15 say "City: 

15 say "PCP city Code: 

15 say "Data Rate: 
if *n>0 say " AUTO" 
( 10 15 say "Area Code: 
( 11 15 say "Phone Number: ",E 
• 13 10 say -2. enter new RAS data" 

I 17 1 say "Enter selection (or to return to main menu): 

LABEL ASKHODE 

« 17 48 say " 
t 17 48 
input 

if value-3 %m-100;READ PCPHENU 

if value-1 GOTO HAKECALL 

if value02 bell l;GOTO ASKMODE 



Get PCP Outdial City Code 



LABEL SETCITY 

els 

box 1 1 18 79 

if %p-0 

8 3 28 say "PC-Pursuit city Choices" 
else 

%d-tp 

GOSUB CITYNAME; . get current city name into A 

6 3 10 say "PC-Pursuit Cities (Currently Connected to ",A,")" 
endif 

tx-1;. starting city number 

LABEL COLUMN 

%d-%x 

GOSUB CITYNAME 

%y-4 ; %w-tx+4 

if »x<10 %y-5 

if %x>12 ty-28;%w-lx-8 

if %x>24 *y-52;%v-%x-20 

t %w %y say %x,". ",A 

%x-%x+l 

if tx<35 GOTO COLUMN 

6 20 5 say "City code selection (or to return to main menu):" 

LABEL ASKCITY 

t 20 56 say " 

t 20 5S 

input ; %o -value 

if %c-0 tm-100,'READ PCPMENU;. return to main menu 
%d-%c;GOSUB PCPCODE;. set PCP code and area oode data 

if %c-%p GOTO SETPHONE; . if already connected, skip baud query 



Get baud rate to use if a new city is specified. 



LABEL SETBPS 

els 

box 5 5 13 54 

■ 7 10 say "Data rate to use for new city (",C,"):" 
t 9 15 say "1. 2400 AUTO" 

■ 10 15 say "2. 1200 riXED" 
« 11 15 say "3. 2400 FIXED" 

15 1 say "Enter selection (or to return to main menu): 

LABEL ASKBPS 
« 15 48 say " 
C 15 48 
input 

if value-1 %b«2400;B-"24";%n-2;GOTO SETPHONE 
if value-2 %b-1200;B-"12";%n-0;GOTO SETPHONE 
if value-3 %b-2400;B-"24";%n-0;GOTO SETPHONE 

.. if bad answer, ring bell and get another answer 

bell 1 
GOTO ASKBPS 



LABEL SETPHONE 

els 

if %g-0 %a-tf;GOTO SETNUHB 

box 5 5 12 50 

I 7 10 say "Area Codes for PCP City Code ",C 
t 9 15 say "1. main area code: ",*f 
I 10 15 say "2. alternate area code: ",%g 

14 10 say "Area code selection: " 

LABEL ASKAREA 

t 14 32 say " 
• 14 32 
input 

if value-1 %a-%f ;%h-0;GOTO SETNUHB 
if value-2 %a-%g,-GOTO SETNUHB 

.. if invalid response, ring bell and ask again 

bell 1 

GOTO ASKAREA 



(Listing 4 continued on next page) 
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(Listing 4 continued from previos page) 



LABEL SETHUMB 



els 



say "/n/nArea code io ",%a 

say "/n/nEnter phone number (M#-##M): " 
accept E,8 

if %a»%g E""{F}-{E}"; . prefix the area code to the number 
if %h>0 E-"1-{E}";. if required, prefix "I-" to number 

eay "/nEnter system name (optional): " 
accept P 

%d-%c;GOSUB CITYHAME 

label HAKECALL 

say "/n/nReady to place the following call:/n" 

say "/n System Name: ",F 

say "/n City: ",A 

say "/n PCP City Code: ",C 

say ~/n Data Rate: ",%b 

if %n>0 say ■ AUTO" 

say "/n Area Code: ",%a 

say "/n Phone Number: ",E 

say "/n/nData Correct (Y//n)? " 
accept A,l 

conp ".{A}" ".";if value-1 GOTO MAKECALL1 

comp A -Y-;if value-1 GOTO HAKECALL1 

GOTO SETCITY; . start over again 



LABEL HAKECALL 1 



D-C;. 

READ PCPCALL; 



set PCP city code 
chain to PCPCALL script 



SAGE MICROSYSTEMS EAST 

Selling & Supporting the Best in 8-Bit Software 

e Automatic, Dynamic, Universal Z-Systems 

- Z3PLUS: Z-Systeni for CP/M-Plus computers ($70) 

- NZCOM: Z-System for CP/M-2.2 computers ($70) 

- ZCPR34 Source Code: if you need to customize ($50) 

• Plu*Perfect Systems 

- Backgrounder ii: CP/M-2.2 multitasker ($75) 

- ZDOS: date-stamping DOS ($75, $60 for ZRDOS owners) 

- DosDisk: MS-DOS disk-format emulator, supports subdirecto- 
ries and date stamps ($30 - $-15 depending on version) 

• BDS C — Including Special Z-System Version ($90) 
a Turbo Pascal — with New Loose-Leaf Manual ($60) 

• SLR Systems (The Ultimate Assembly Language Tools) 

- Z80 Assemblers using Zilog (Z80ASM), Hitachi (SLR180), or 
Intel (SLRMAC) Mnemonics 

- Linker: SLRNK 

- TPA-Based ($50 each) or Virtual-Memory (Special: $160 each) 

• ZMAC — Al Hawley's Z-System Macro Assembler with Linker ($50) 

• NightOwl (Advanced Telecommunications) 

- MEX-Plus: automated modem operation with scripts ($60) 

- MEX-Pack: remote operation, terminal emulation ($100) 

Next-day shipping of most products with modem download and support 
available. Order by phone, mail, or modem. Shipping and handling $3 per 
order (USA). Check, VISA, or MasterCard. Specify exact, disk format. 

Sage Microsystems East 

1435 Centre St., Newton Centre, MA 02159-2469 

Voice: 617-965-3552 (9:00am - 11:30pm) 

Modem: 617-965-7259 (pw=DDT) (MABOS on PC-Pursuit) 



Listing 5: PCPCALLMEX 

. . PCPCALL. HEX (04/16/90) 

. . This script performs th* steps necessary to connect to the 
. . designated city and remote system. 



%m-100; . 
%u-0; . 



clear menu selection 

flag to Bhow initial run thru script 



. . *** section omitted here *** 

. . Branch depending on whether we are presently connected to no 
. . city, to the requested city, or to a different city. 



if %p-0 GOTO NEWCITY;. 
if %C-%p GOTO LOCAL; . 



no city connected presently 
already connected to desired city 



Disconnect from wrong city 



%d-%p;GOSUB CITYNAHE; . get name of currently connected city 
say "/n/nDisconnecting from ",A," ..." 



max number of tries 



LABEL DROPCITY 



screen off 

sendout "/r(/r"j. try to return to PCP command mode 

wait string 2 "<>";. we should get '€* prompt 

if value>0 GOTO DROP1; . if we do, continue below 

*z«%z-l; . else decrement count 

. . abort if count expired 

if %ss<l A""Cannot quit current city";GOTO ABORT 

GOTO DROPCITY;. try again 



LABEL DROP! 

screen off 
sendout "D/r";. 
%p»0;. 
%v-0;. 
screen on 
say "OK";. 



tell PCP to disconnect from city 
show no city connected 
show not in Vadic mode 

tell user that it worked 



Connect to new city 



LABEL NEWCITY 



screen on 



. . We do different things depending on whether or not we have 
.. exhausted the first set of attempts. 



end any line of screen output 
show no longer first time 
number of tries into variable 



if %u-0 

say "/n"; . 

%u-l;. 

%e-%t;. 
else 

A"" city code" 

gosub GETD; . gets number of times to try 

say "/nCalling " ,F, "/n"; . tell user whom we are trying to reach 
endif 

%d-%c; GOSUB CITYNAME 

say "/nDialing city code ",D," ( ",A, ")"; .report the city code we 

are dialing 



%z-l; 
%o-l; 



LABEL CITYCODE 



count of tries 

indicate no auto stepdown yet 



if «z>%d goto MORETRIES 

sleep 1 

screen on;say "/n try #",%z," of ",%e," at " ,B, "00bps. .. ■ 

; screen off 
%z-%z+l 

sendout "C D//"; sendout D; . city code 

sendout "//"; sendout B; . baud code 

sendout ■ , " ; sendout "PCP_USERID" ; . user id 
sendout ",";sendout "PCP_PW";. user password 
sendout "/r" 

wait string 4 "CONNECTED- "BUSY" TAIL" 

. . If we connected, set %p to show new city connected and %u to 
.. indicate the first pass at connecting to the specified RAS. 

if value-1 %u-0;%p«%c;GOTO LOCAL 

screen on 

if value-3 say "Failed Call";goto MORETR1 

if value-2 say "Busy" 



(Listing 5 continued on next page) 
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(Listing 5 continued from previous page) 


if value-0 say "Ho Response" 


screen on 


goto CITYCODE 


if value-0 say "/nVadic Mode Failed/n";goto RE IN IT 


LABEL MORETRIES 


say "/nRemote modem now in Vadic Mode" 


if %n-0 goto HORETR1;. no auto step down 


%v-2;. show Vadic mode 


if %o-0 goto MORETR1;. already stepped down 






LABEL DIAL1 


%o-0;. show now stepped down 




if %b-2400 B-"12";%z-l;GOTO CITYCODE;. reset trial count %z 


lr»0; . initialize ring count 




screen on; say "/n/nTry #",%*," of ",%e," (at ",B,"00 bps)/n" 


LABEL HORETR1 


sendout "D"; sendout E; sendout "/r" 


A"" city code" 


LABEL DIAL2 


GOSUB ASKMORE 


screen on 


if value-1 GOTO NEWCITY;. try again to reach new city 


wait string 25 "ANSWER" "BUSY" "DIAL TONE" "RINGING... " 




if value-1 goto SUCCESS 


READ PCPMENU; . else chain back to main nenu 


if value-2 goto BUSY 




if value -3 goto DIAL TONE 
if value<>4 goto BADCODE 




In right city; try connecting to specified system 


. . *** many routines omitted *** 
LABEL SUCCESS 






screen on 


LABEL LOCAL 


say ""G/n/nCONNECTED TO HOST SYSTEM/n/n" 


screen on 


READ PCPCONN; . chain to short script to free memory 


%d-tp; GOSUB CITYMAME 




say "/n/nConnected to city code ",D," (",A,")" 






. . Subroutines 


.. initialize destination modem to make sure it is still alive 






. . Ask user for the number of times to connect and put answer is 


if %v-2;. if in Vadic node, reinitialize modem 


.. %e. If the answer is less than 1, then use a value of 1. 


sendout "I/r";. exit from it 




%v-0; . show initialized modem 


PROC GETD 


sleep 1 


say "/nTry how many times to connect to", A,"? " 


endif 


input 




%e -value 


LABEL REINIT 


if %e<l %e-l 


%z-3;. max attempts to initialize modem 


ENDP 


LABEL REINIT1 




if %z<l A-"Remote modem failure"; goto ABORT 


.. Ask if user wants to continue trying to connect. Return with 


%z-%z-l 


.. the answer in VALUE, 1 if YES, if NO. 


screen on; say "/n initialize remote modem... "; screen off 




sleep 1 


PROC ASKMORE 


sendout "ATZ/r" 


LABEL ASKAGAIN 


wait string 3 "OK" 


screen on 


if value-0 goto REIMIT1 


•ay "/n/nTry" f A," some more (Y//N)? " 




bell 1 


. . Call destination system 


accept C,l 




screen off 


LABEL LOCALAGAIH 


comp C "Y" 




if value-1 ENDP 


.. *** section omitted *** 


comp c "N" 




if value-1 value-O; ENDP 


LABEL DIAL 


bell 1 




goto ASKAGAIN 


sendout "*E/r";. enter Vadic mode 




wait string 3 "*" 


. . *** remaining routines omitted *** 





Listing 6: 


Script 


PCPCONN.MEX 




.. PCPCONN. HEX 


(02/08/90) 








. . This short script is run once the destination system has 
. . reached. 


been 


screen on 

els 

say "Connected 


to ",F," at 


"iB^OO bps/n/n" 

enter terminal mode 




LABEL LOOP 

say "/nEnter a single HEX command 

accept A 

comp A "M" 

if value-1 READ PCPMENU 

<*•> 

SOTO LOOP 


(or M for menu) : " 





system. PCPCALL then chains to PCPCONN (Listing 6), which 
drops one into terminal mode with the function keys programmed 
to ease logging in. It would not be hard to have the script first call 
a subroutine script to perform the login operation automatically. 
The easiest way would be to store a number in a numerical vari- 
able as a flag and the name of the login script file in a string 
variable. Unfortunately, it's not clear that we have a free string 
variable to use. One possibility would be to use the system name in 
variable F. One could run it using the command "DO {F}". 

Conclusion 

I hope this extended example will give you a better idea of how 
and to what extent MEX script commands can be used to auto- 
mate telecommunications tasks. Please let me know if you have 
some ideas to improve these scripts. • 



current city and then connecting to the new city. 

The script has to allow for things not always going right, at least 
not the first time. You should particularly note the pains it takes to 
reset and test the PCP outdial modem and to put it into Racal- 
Vadic mode. 

If the outdial modem is busy or if the RAS is busy, the script 
will ask the user whether to make additional attempts and if so 
how many. The script is very careful to keep the user informed of 
exactly what is going on. 

If all works out, we eventually end up connected to the remote 
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The Z-System and Turbo Pascal 

by Joe Wright, Alpha Systems 



"Real Programmers Don't Eat Quiche" really started some- 
thing. Real Programmers don't write applications, only tools. Real 
Programmers don't write in High-Level languages, only in Assem- 
bler. And so on... 

These statements become popular cliches only because they 
are largely true. Authors of High-Level languages strive for gener- 
ality and avoid system-specific constructs or references. Authors of 
system-level programs find High-Level languages insufficient to 
the task and almost always choose Assembler. 

I suppose I am primarily a system-level or "Real" programmer 
and have never had much use for High-Level stuff (I mean, can 
you really write a BIOS in Fortran?). I have written a few 'applica- 
tion' programs in dBASE II (a High-Level language) but have 
spent most of my time writing 'tools' in Assembler. 

As some of you already know, I have had an abiding interest in 
ZCPR3 and the Z-System for some years now. I am the author of 
NZCOM and its predecessors dating back to 1985. My company, 
Alpha Systems, began distributing Borland's Turbo Pascal 3.0 
(CP/M and PC-DOS versions) earlier this year. In order to handle 
Tech Support phone calls, I bent myself to the awesome task of 
learning a new High-Level language. 

Well, its not really that hard. Pascal was designed as a means to 
teach programming (to un-real programmers?) and does the job 
well. I'm learning. 

The Z-System derives much of its power and flexibility from 
the use of complex data structures such as Z3ENV and Z3MSG 
segments. Attempts to address these structures in the context of a 
High-Level language have not borne fruit, until now. Please let me 
digress for a moment. 

A Z3 utility (.COM file) has a special 'header' associated with it 
which includes a 'pointer' to Z3ENV, the Environment Descrip- 
tor. Knowing the address and the structure of Z3ENV, the Z3 
utility can have complete access to the entire Z-System, especially 
through the use of SYSLIB, Z3LIB and VLIB subroutine librar- 
ies. Most of us know this already. Let's continue with something I 
just found out. 

Turbo Pascal has a Record construct allowing the definition of 
complex data structures as variables in Pascal terms. This means 
we can define Z3ENV, Z3MSG, Z3NDIR, Z3CL and other Z- 
System structures as Pascal records of variables. If we only knew 
where they were. 

Further, Pascal has a Pointer construct to point to a record of 
variables. If we only knew where the pointer was. 

OK, you guessed it. We patch TURBO.COM so that it looks 
like a Z3 utility and can be 'installed' by the command processor 
which puts the Z3ENV address at 109H in the .COM file. In 
Pascal, we define the contents of 109H as a Pointer variable to a 
Record of variables, the Environment Descriptor. From now on, 
we can access the entire Z-System as Pascal variables. 

I apologize if this seems a bit obtuse to the casual reader. In 
effect, the High-Level Application programmer in Pascal can now 
have complete access to Z-System and the "Real" system-level 
programmer, who can't even spell quiche, is no longer restricted to 
Assembler. Many otherwise complex Z-System "tools" can be 



written quickly and easily in Turbo Pascal. 

To demonstrate this, I have written NZ-TOOL.BOX as shown 
in Listing 1 for Turbo Pascal. It contains the Z-System structures 
defined as Records and a few SYSLIB and Z3LIB functions in 
Pascal. 

I offer this tool.box and the simple programs which follow with 
abject humility and apology to the veteran Pascal programmer. I 
am told that "It doesn't even look like Pascal" by more than one. 
"It looks like Assembly Language", they say. 

Well, what do you expect from Joe? I have been programming 
in Assembler for six years and in Pascal for six weeks. Style aside, it 
works. Please dress it up for me. Thanks. 

The CPY and PD programs shown in Listing 2 are perhaps too 
simple to be useful Z3 utilities. They are here to demonstrate the 
use of the NZ-TOOL.BOX routines. 

Well, I'm out of breath (and out of paper) and will get off my 
soapbox for now. I hope that I have tweaked more than a little 
interest in both Z-System and Turbo Pascal. In the case that I 
have succeeded, you can get either or both from: 

Alpha Systems Corporation 

71 1 Chatsworth Place 

San Jose, CA 95128 

(408) 297-5594 



Listing 1 



(* NZ-TOOL.BOX 1.0 for Turbo Pascal 3.0 
Copyright (C) 1989 Alpha Systems 

Author: Joe Wright 
Date: 20 Sept 89 
Version: 1.0 

Invoke TURBO. COM with a Z-System alias, TP.COM, as follows.. 

1 — > GET 100 TUKBO.COM; 

2 — > POKE 103 5A 33 45 4E 56 01 00 00; 

3 — > SO 

ThiB puts a Z3EMV Type 1 header at the beginning of TURB0.COM 
so that GO will 'install' the Environment address at 109H. 
COM files created by TURBO.COM will also contain this header 
and therefore be Z3 utilities. 

This version of the TOOL.BOX describes the entire Z-System in 
terms of Turbo Pascal Records. The Record structure and Turbo 
Pascal Pointers will allow the veteran Pascal programmer complete 
access to the Z-System Environment and by implication, a 
description 

of its entire structure. 

The Z-System assembly language programmer is presented with Pascal 
functions and procedures with familiar SYSLIB and Z3LIB names so 
that he can ' call ' his favorite subroutines within Turbo Pascal 
without re-inventing the wheel. 

Programming style seems to vary according to the square of 
of programmers (or square programmers?) and no one should feel 
limited by the examples in this TOOL.BOX. Think of it as a 
demonstration. In the end, do it your way. 

Load the Tool Box into you program with the Turbo Pascal 
{$1 NZ-TOOL.BOX) insertion directive. 

Turbo Pascal is not upper/lower case sensitive. He tend to use 
mixed case for readability. In order to distinguish among Turbo 
Pascal Standard declarations and our own, I try to follow the 
convention that . . 
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(Listing 1 continued from previous page) 



GoToBed ie a Turbo Pascal defined Word or Identifier 
GOTOBED is the User Definition 
gotobed is the User Declaration 

Mixed case is Pascal, UPPERCASE is our own definition and 
lowercase declares our definitions. 



') 



{ User-Defined Global Types } 

Type 

SIRS - String! 8]; 
STR21 - string [21]; 



ARR8 


- Array[l. 


.8] of Char; 


ARR3 


- Axray[l. 


.3] of Char; 


ARKS 


- Array[l. 


.5] of Char; 



{ Dir Mane or Password 
{ HDIRHAME:FXLENAME.TYP 

{ Name or Password array 

{ rile type array 

{ Five-char ID like Z3ENV 



SECTOR - Array[0..127] of Byte; { Standard CP/M Unit Record 
FCBPTR ■ 'FCBREC; 



FCBREC - 






Record 






DRIV 


Byte; 




NAME 


arr8; 




TYP 


arr3; 




EXT 


Byte; 




SI 


Byte; 




S2 


Byte; 




RC 


Byte; 




ALLOC 


Array[0. 


.15] of Byt 


CR 


Byte; 




RREC 


Integer; 




RERR 


Byte 




End; 







{ This describes the Z3MS6 structure. } 
MSGPTR » "MSGREC; 



MSGREC - 




Record 




ERFLG 


: Byte; 


IFLEV 


: Byte; 


IFSTS 


: Byte; 


CMDST 


: Byte; 


ERADR 


: Integer; 


PRGER 


: Byte; 


ZEXMSG 


: Byte; 


ZEXRUN 


: Byte; 


ZEXNXT 


; Integer; 


ZEX1ST 


: Integer; 


SHCTL 


s Byte; 


SCRAT 


: Integer; 


ERCMD 


: Array! 1.. 32] °t Char 


REGIS 


: Array[0..31] of Byte 


End; 




This describes the Z3CL structure 


MCLPTR - "MCLREC; 


MCLREC - 




Record 




NXTCHR 


: Integer; 


MCLMAX 


: Byte; 


MCL 


: String[ 203]; 


End; 







Z3NDIR : 


ndrptr; 








Z3HDIRS : 


Byte; 








Z3CL : 


nclptr; 








Z3CLS : 


Byte; 








Z3EHV : 


Integer; 








Z3EKVS : 


Byte; 








SHSTK 


Integer; 








SHSTXS 


Byte; 








SHSIZE 


Byte; 








Z3MSG 


msgptr; 








EXTFCB 


fcbptr; 








EXTSTK 


Integer; 








QUIET 


Byte; 








Z3WHL 


"Byte; 








SPEED 


Byte; 






) 


MAXDSK 


Byte; 






) 


MAXUSR 
DUOK 


Byte; 
Byte; 






} 


CRT 


Byte; 






} 


PRT 


Byte; 






> 


COLS 
ROWS 


Byte; 
Byte; 






} 


LINS 

DRVEC 

SPAR1 

PCOL 

PROW 

PLIM 

FORM 

SPAR2 

SPAR3 

SPAR4 

SPARS 

CCP 

CCPS 

DOS 

DOSS 

BIO 


Byte; 

Integer; 

Byte; 

Byte; 

Byte; 

Byte; 

Byte; 

Byte; 

Byte; 

Byte; 

Byte; 

Integer; 

Byte; 

Integer; 

Byte; 

Integer; 








SHVAR 


• Array[l. 


.111 


of Char 




FILE1 


: Array! 1. 


•HI 


of Char 




FILE2 


: Array [1. 


.11] 


of Char 




FILE3 


: Array[l. 


•"I 


of Char 




FILE4 


: Array! 1. 


.111 


of Char 




PUBLIC 


: Integer; 








End; 









Z -Systems . } 



MEMORY - Array [0..S7FFE] of Integer; 

PATPTR - 'PATREC; 
PATREC - 

Record 

PATH : memory; 

End; 

NDRPTR - "NDRREC; 
NDRREC - 
Record 

DU : Integer; 
NAME : arr8; 
PASS : arr8; 
End; 

{ The following Record Structures define the 23 Environment of 
any NZ -System. } 

ENVPTR - *ENVREC; 



IVREC - 
Record 






ENV 


: Byte; 




CBIOS 


: Integer; 




Z3ID 


: Array[1..5] of Char 


EHVTYP 


: Byte; 




EXPATH 


: patptr; 




EXPATH8 


! Byte; 




RCP 


: Integer; 




RCPS 


: Byte; 




IOP 


: Integer; 




IOPS 


: Byte; 




TCP 


: Integer; 




FCPS 


: Byte; 





{ Global Variables } 

{ These are the Absolute (External) variable assignments which 
give the Turbo Pascal program access to everything we know. > 



Var 








WBOOTV 


; Integer 


Absolute 


$0001 


IOBYTE 


: Byte 


Absolute 


$0003 


CDISK 


: Byte 


Absolute 


$0004 


BDOSV 


: Integer 


Absolute 


$0006 


FCB1 


: fcbrec 


Absolute 


$005C 


FCB2 


: fcbrec 


Absolute 


$006C 


TBUFT 


: String! 126 


Absolute 


$0060 


DBUFF 


: sector 


Absolute 


$0080 


Z3EADR 


: envptr 


Absolute 


$0109 



SPEC1 


: str21; 


SPEC2 


: str21; 


DIRS 


: Btr8; 


MAKE 


: strS; 


PASS 


: str8; 


SOURCE 


: File; 


DESTIH 


: File; 


CURDU 


: Integer 


SRCDU 


: Integer 


DSTDU 


: Integer 



{ These Global Variables are used by the new Functions and Procedure! 
and the Main program to pass parameters among themselves . } 

{For DIRECTRliriLENAME.TYP) 
{ror DIRECTRY:FILENAME.TYP) 
{For D:, U:, DO: or DIR: J 
{Directory Name} 
{Directory Password) 

{File being Read} 

{File being Written) 

{Current (default) Drive/User) 

{Source D/U} 

{Destination D/U} 

{ From here on, we will collect various User-Defined functions 
and procedures which emulate SYSLIB and Z3LIB subroutines of 
the Z-System. To the extent that they may 'call* each other, 
they are arranged here such they are Declared before they are 
called, SYSLIB, Z3LIB, VLIB, in that order. Turbo Pascal is 
itself rich enough to provide most of the functions we need. } 

Procedure CAPSTR(Var S:str21); 

Var I : Integer; 

Begin 

for i :- 1 to Length(s) do s{i] :- UpCase(e[i]) 
End; 

Function PHEX(M,B: Integer) :str8; 
Var H : strS; I, C : Byte; 
Begin 

h[0] :- #0; { Clear the string ) 

For i :■ b Downto 1 Do 

Begin 

o :■ n and 15; n :■ n shr 4; 
If a < 10 Then o :- o+48 Else o :- c+55; 
Insert(Chr(c) r h,l) 
End; 

phex :• h 
End; 
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(Listing 1 continued from previous page) 




Function RETUD: Integer; 








dnacan :■ du 




Begin 








End; 




retud :- 256 * (Bdoe(25)+l) + Bdoa(32,$FF) 










End; 








Function NAHSTR(Nam:arr8) :str8; 
Var I : Integer; Str : str8; 




Procedure LOGUD ( DU : Integer ) ; 








Begin 




Begin 








str[0] :- #8; 




Bdos(14,Hi(DU)-l); Bdos(32 ,Lo(DU) ] 








for i :■ 1 to 8 do etr(i] :■ nam[ij; 




End; 








i :» Pos( ' ' ,str) ; 
if i o then 




Procedure PDU{du: Integer) ; 








str[0] :- Chr(i-l); 




Begin 








namstr :■ str 




Write(Chr(Hi(du)+64) ,Lo(du) , ' : ' ) 








End; 




End; 








Function DUTDIR(du: Integer) : Boolean; 




Function 6ETNDR: Integer; 








Var ndir : ndrptr; 




Begin 








i : Integer; 




getndr :■ 0rd(z3eadr~ .z3ndir) 








Begin t 




End; 








name[0] :■ #0; 
paaa[0] :- #0; 




Function DIRSCAN(S:str8) : Integer; 








ndir : * Ptr ( getndr ) ; 




Var HDIR : ndrptr; 








Repeat 




- D, I : Integer; 








if du ■ Swap ( ndir " .du) then 




Begin 








begin 




d :- 0; 








name :■ namstr ( ndir * .name) ; 




ndir :■ Ptr( getndr); 








pass :■ namstr (ndir" .pass) ; 




if ndir'.du o then 








end; 




Repeat 








ndir :» Ptr (Ord( ndir )+SizeOf (ndrrec) ) ; 




name[0] :- #8; 








Until (Length(name) o 0) or (Lo(ndir" .du) - 0); 




for i :«• 1 to 8 do name[i] :■ ndir~.name[i]; 






dutdir :■ Length (name) <> 




i : ■ Pos ( ' ' , name ) ; 








End; 




if i o then name[0] :- Chr(i 


-D; 










if e ■ name then d :■ Swap (ndir 


.du) elBe d 


- 0; 




Function GETWRL:Boolean; 




ndir :■ Ptr (Ord( ndir )+SizeOf (ndrrec) ) ; 






Begin 




Until <d o 0) or (Lo(ndir* .du) - 


0); 






if z3eadr* .z3whl" ■ then 




dirscan :- d; 








getwhl :■ false 




End; 








else 

getwhl :■ true 




Function DUSCAN(S:str8) : Integer; 








End; 




Const d - 'ABCDEFGHIJKLMNOF' ; 












Var du, uer, cod : Integer; 








Procedure SETWHL ( B : Byte ) ; 




Begin 








Begin 




du :■ curdu; 








z3eadr A .z3whl" :■ b 




if Length(s) o then 








End; 




begin 












if PoB(s[l],d) o then 








Function GETDUOK:Boolean; 




begin 








Begin 




du :- Pos(s[l],d)*256 + (du 


and 255); 






if z3eadr~.duok ■ then 




Delete(s,l,l) 








getduok :■ false 




end; 








else 




if Length(s) <> then 








getduok :- true 




begin 








End; 




Val ( s , usr , cod ) ; 












if cod <> then 








Procedure PARSE(Var S:str21); 




du :* curdu else du :- (du and -256) + 


(usr and 


31) 


Var P : Integer; 




end; 








Begin 




end; 








dirs[0] :■ #0; { Clear the string } 




duscan :■ du; 








p :- Pob(*:',b>; 




End; 








if p o then 
begin 




Function DNSCAN: Integer; 








dira :■ Copy ( e , 1 ,p-l ) ; 




Var du : Integer; 








Delete(a ( l f p) 




Begin 








end; 




du :• dirscan ( dira ) ; 








End; 




if du ■ then du :■ duacan(dirB) ; 








{ End of NZ-TOOL.BOX 1.0 } 












Listing 2 




Program PD; 

{ Author: Joe Wright 








Repeat 

if x > 20 then x :« 1 else x :- 35; 




Date: 22 Sep 89 








y :- y+i; 

GoToXY(x # y div 2); 




Version: 0.1 










Poorman's version of PWD.COM to demonstrate NZ-TOOL.BOX and 


if getduok then pdu(Swap(ndir*.du) ) ; 
name :** namstr (ndir* .name) ; 




access to the Z3NDIR structure. 








pasa :- namstr (ndir" .pass) ; 




} 








x :- x+5; 




{$1 nz-tool.box) 








GoToXY(x,y div 2); 
Write ( name ) ; 




Var NDIR : ndrptr; 
X, Y : integer; 








if (fcbl.name[l]-'P' ) and getwhl then 
Begin 

x :■ x+9; 
GoToXY(x,y div 2); 




Begin 








LowVideo ; 




ndir :■ Ptr( getndr); 

name :■ namstr (z3eadr~.extfcb~ .name) ; 








Write(' Pass: ',panB); 
NormVideo; 




y :- 7; 








End; 




x :- 25; 








WriteLn; 




ClrScr; 








ndir :- Ptr (Ord( ndir) +SizeOf (ndrrec) ) ; 










Until Lo(ndir'.du) ■ 




WriteLn( 'Print Working Directories'); 








End; 
End. 




if fcbl.name[l] » '/' then 










Begin 












WriteLn ( ' Syntax : ' , name , ' [ P 


■); 










WriteLn( ' The P option will show 


Passwords if 


Wheel is 


ON* ); 






End 












else 
Begin 








{ Program: CPY.PAS 










Author: Joe Wright 




Write(' Z3 Wheel is 0'); 








Date: 10 Sept 89 




if getwhl then WriteLn('H') else WriteLn( 'FF' ) 










if ndir'.du o then 








(Listing 2 continued on 


next page) 
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(Listing 2 continued from 


previous page) 


Version: 0.1 






specl :■ spec2; 
dstdu :■ dnscan; 


This single-file copy program uses the NZ-TOOL.BOX to add 






if (dstdu ■ srcdu) and (specl - spec2) then 


many Z3LIB functions to Turbo Pascal programs. 






Write (bel, "Don" "t be silly..') { source "destination } 
else 

begin {copy} 


Version 0.2 is modified for the changes in NZ-TOOL.box 












logud(dstdu) ; { Log into destination area } 


} 






Assign(destin, specl} ; 
if not o then 


Program CPY; 






begin 


{$1 nz-tool.box} 






{SI-} 


{ Constants are used very much like EQUates. } 






Reset(destin) ; 


Const 






{$i+> 


ver "0.2; { Version Number } 






If lOresult - then 


cr - "M; 






begin 


If - "J; 






pdu ( dstdu ) ; 


bel - "G; 






if dutdir( dstdu) then Write (name,' '); 


recs ■ 128; { Sector size } 






Write (specl, ' Exists. Overwrite? (Y or N) •); 


bufs - 128; { 128 of them for 16k (Max) > 






Read(Kbd,ch); WriteLn(ch); 


Var 






if UpCase(ch) o 'Y' then Halt; 


inpbuf : Array[l. .buf s,l. .recs] of Byte; 






end; 


count : Integer; 






end; 


i : Integer; 






Rewrite ( destin ) ; { erases any existing file } 


cks : Integer; { Checksum variable } 






{ Tell the user we're up to something } 


ch : Char; { Keyboard response } 






Write ( ' Copying ' ) ; 


o : Boolean; { Overwrite option } 






pdu (srcdu) ; 


n : Boolean; { Ho verify option > 






if dutdir(srcdu) then Write (name,* '); 
Write (spec 2, ' to ' ) ; 


BEGIN {ning of CPY. PAS} 






pdu (dstdu) ; 


name :- namstr(z3eadr* .extfcb'.name) ; 






if dutdir( dstdu) then write (name,* '); 


if fcbl.name[l] < '0' then {Help} 






WriteLn( specl) ; 


Write { 






cks :■ 0; { clear the checksum word } 


name, 1 Ver ',ver:l:l,' Single-File Copy Program' ,cr, If , 








' Syntax: ' ,name, ' [dir: Jsource [ [dir: Jdeotination] [ / 






Repeat 


oo) ' ,cr,lf , 






Write ('.'); 


' where ''/oo' 1 is [OJverwrite and/or [N]o Verify options.' 
) 






logud ( srcdu ) ; 

BlockRead ( source , inpbuf , bufs , count ) ; 


else 






if not n then 


begin {source} 






for i !■ to (count*recs) -1 do 


o :■ false; 






cks :» cks + Mem[Addr(inpbuf )+i); 


n :■ false; 






logud (dstdu) ; 


curdu :■ retud; { retud from nz-tool.box } 






BlockWrite ( destin , inpbuf , count ) ; 


dstdu :■ curdu; 






Until count "0; 


i !» Pos{ ' / ' ,tbuf f ) ; { check for '/' on command line } 








if i <> then 






Close(destin) ; 


Repeat 






if not n then 


i :- i+1; 






begin {verify} 


if tbuff[i] ■ '0' then o :« true; 






Reset ( destin ) ; { Prepare to read it } 


if tbuff[i] - 'N' then n :- true; 






Write(cr,lf , ' Verifying ' ) ; 


Until tbuff[ij - #0; 






pdu (dstdu) ; 


sped :■ ParamStr(l); 






if dutdir( dstdu) then Write (name, ' '); 


parse ( specl ) ; { parse dir: part to dirs } 






Wr iteLn ( spec 1 ) ; 


srcdu :■ dnscan; { dnscan resolves d:, u:, du: and dir: } 








logud(srcdu) ; { log it in } 






Repeat 


Assign (source, specl) ; 






Write ('.'); 


{Si-} 






BlockRead ( destin , inpbuf , bufs , count ) ; 


Reset ( source ) ; { open the input file } 






for i :■ to (count*recs)-l do 


{$! + > 






cks :- cks - Hem [ Addr ( inpbuf )+iJ; 


if lOresult <> then 






Until count - 0; 


Write ( 'Can' ' t find ' , specl) 








else 






if cks o then Write(bel,cr,lf , ' Tailed! •) 


begin {destin} 






end; {verify} 


spec 2 :« specl; 






end; {copy} 


specl :« ParamStr(2>; 






end; {destin} 


parse (specl) ; 




end; 


{source} 


if (Length(specl) - 0) or (specl[l] - '/*) then 


END. {of 


CPY. PAS} 
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Embedded Applications 

Z80 Communications Gateway, Part 1 

by Art Carlson 



When someone mentions their com- 
puter, we expect to see a keyboard, CRT 
display, and disk drives. But embedded 
controllers are also computers, even 
though they may not have any of the usu- 
ally expected peripherals. They also use 
unfamiliar processors with strange archi- 
tectures. Leaving the secure world of pre- 
packaged desk top computers for the do- 
it-yourself world of embedded controllers 
can be rather frightening — it's something 
like taking the training wheels off your 
bike. 

The design and application of embed- 
ded controllers is very interesting, and it is 
one of the few areas which provide signifi- 
cant opportunities for small entrepre- 
neurial businesses. There are also many 
employment and consulting positions 
available for people with embedded con- 
troller application expertise. 

I feel that working with embedded con- 
trollers can be fun, useful, and rewarding. 
The purpose of this series is to encourage 
you to explore the world of embedded 
controllers with the least trauma. Here, we 
will cover the low-level basics and use the 
more familiar tools in order to tempt you 
to get started on some beginning, but yet 
useful, projects. Other more advanced 
projects using different processors and 
tools will be covered in other articles. 

Selecting the level at which to start is a 
very significant problem with any how-to- 
do-it series. Where ever we begin will be 
too advanced for some, and overly simple 
for others. Hopefully we will cover most 
needs through a combination of different 
articles. I don't intend to spend a lot of 
time on boring theory and facts to memo- 
rize, but rather will concentrate on learn- 
ing by doing. An old Chinese proverb says, 
"I hear and I forget, I see and I remem- 
ber, I do and I understand." My goal is to 
get you to assemble and program some 
simple controllers so that you will feel con- 



fident enough to tackle more advanced 
projects of your own choosing. 

Controllers versus Processors 

One of the most confusing aspects of 
embedded controllers is understanding the 
difference between the chips used in our 
desk top microcomputers and the chips 
used in embedded controllers. Our micro- 
computers generally use a microprocessor 
such as a Z80 (CP/M); 8088, 80286, 
80386, etc. (IBM PC series); or 68000, 
68020, 68030, etc. (Apple Macintosh se- 
ries). Embedded controllers frequently use 



"I hear and I forget, 
I see and I remember, 
I do and I understand." 

An old Chinese proverb 



a microcontroller such as an 8031, 8096, 
68HC11, 6803, or Z8. But, it gets very 
confusing because many embedded con- 
trollers use microprocessor chips such as 
the Z80, 80186, and 68000. Also, desktop 
microcomputers use microcontrollers, in 
addition to the main microprocessor, for 
disk drives keyboards, etc. Intel made a 
wise move when they changed the name of 
their 1989 edition Embedded Control Ap- 
plications Handbook to Embedded Appli- 
cations for the 1990 edition. I'll probably 
follow their lead and use the term Embed- 
ded Application, and not be concerned 
with whether the chip is a processor or a 
controller. We'll let others spend their 
time and effort on debating the semantics 
while we spend ours on building and pro- 
gramming devices. 

One of the first steps in designing an 
embedded application is to select the chip 



(actually the first step is to define the re- 
quirements, but let's assume that has al- 
ready been done). In order to minimize 
confusion, I'm going to refer to the chip as 
the processor instead of using different 
terms for a microprocessor or a microcon- 
troller. 

For some applications with the main 
emphasis on monitoring and setting I/O 
line status a processor such as the 8031 is a 
good choice. Other applications with the 
main emphasis on calculations and data 
manipulation may be better served with a 
processor such as the 68000. You will 
rarely find an application which can not be 
forced to run on most of the common 
processors. The choice is made based on 
cost, space, familiarity, available tools, 
precedent, stubbornness, and other factors 
which also may (or may not) include the 
features most suitable for the application. 

In general terms, the processors con- 
sidered for applications with a lot of com- 
puting requirements have a very powerful 
set of commands with calculating and 
data manipulation instructions. The more 
recent computing type processors can ad- 
dress a large memory area, and are in- 
tended to work with large program and 
data areas. The processors primarily con- 
sidered as controllers generally contain on- 
chip I/O lines, counter/timers, A/D, serial 
communications, and/or other features 
which are usually provided by separate pe- 
ripheral chips for computer type proces- 
sors. The controller processors are usually 
intended to work with very small memory 
areas, with a fixed (in ROM) program. 
The program memory (8048) may be as 
small as IK of ROM and the data memory 
as small as 64 bytes (that's BYTES not 
KBYTES!). The differences will become 
more understandable as we work with the 
different processors in this and other ar- 
ticles. 

Even though we hear a lot about the 
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16/32 bit 80X86 and 680X0 families which 
are so popular in the desk top computers, 
8 bit processors still rule the embedded 
applications field— in fact they still pro- 
duce a large volume of 4 bit processors for 
embedded applications. 

Enough discussion, let's get started. 

Z80 Communications Gateway 

Embedded applications frequently re- 
quire the use of intra system communica- 
tions both during the development and for 
the end use. The RS-232 serial interface is 
widely used for this purpose, and the abil- 
ity to understand and implement this inter- 
face is essential. 

The purpose of this project is to pro- 
vide an RS-232 communications link 
which can be used with various computers 
so that future projects can be interfaced to 
any computer with an RS-232 port. It will 
also provide the background needed to 
design other serial port implementations. 

I selected the Z80 processor for a num- 
ber of reasons: 1) I had the chips, the tools 
(assembler, debugger, etc.), and the data 
books. 2) I am familiar with the instruction 
set. 3) I felt that the serial port could be 
implemented with the least amount of 
programming by using the Z80 CPU and 
the Z80 SIO. 4) I wanted to compare the 
amount of programming time and hard- 
ware cost/space with a future 8031 im- 
plementation. 5) Many readers have and 
are familiar with the Z80 and its tools, and 
I want to make it easy for them to get 
started. 

The Z80 CPU 

The Z80 is a very versatile processor. It 
has 40 pins (see Figure 1), some of which 
will not be used in the first stage of this 
project. The Z80 instruction set provides 
some very useful communications fea- 
tures, such as INIR (input to memory 
from I/O port and increment pointer until 
byte counter is zero), and OTTR (output 
from memory to I/O port and increment 
address until byte counter is zero). The 
Z80 interrupt protocol is implemented in 
the peripheral chips (Z80 SIO, CTC, PIO, 
DMA) which takes much of the pain out 
of implementing interrupt driven systems. 
Debates on polled versus interrupt designs 
generate lively discussions (arguments?) 
and we'll delve into this in later articles. In 
general, interrupts are faster and reduce 
the processor load but require more hard- 
ware, while polled response is slower and 
uses more processor time but requires less 
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The Z80 Communications Chip set. 







hardware. The Z80 is still currently in pro- 
duction, in fact a new 20 MHz version is 
now available. Technical literature is still 
available from Zilog, but many of the Z80 
books from other publishers have gone 
out of print. We are preparing a Z80 re- 
source directory which will list currently 
available reference material and tools. 

The Z80 has 16 address lines which can 
address 65,536 memory locations. In com- 
puter terms this is referred to as 64K. The 
addressing capability is calculated by rais- 
ing two to the power equal to the number 
of address lines (or address bits). A system 
with 8 address lines can address 2 raised to 
the 8th power, which equals 256 memory 
locations. Two to the 10th equals 1024, 
which we call IK. Any system with 16 ad- 
dress lines has to use some sort of paging 
or memory management system (MMU) 
in order to address more than 64K (two to 
the 16th power). 

The Z80 also has 8 bidirectional data 
lines which we will use to communicate 
with the peripheral chips and the serial 
port. Other pins will be discussed as they 
are used. 

Buffers and Drivers 



TTL and CMOC digital logic circuits 
employ high speed, low voltage, low cur- 
rent signals. These signals are too weak to 
operate relays, light LEDs, or to travel 
over wires off of the board. The Z80 can 
communicate with other TTL level chips 
through its address and data lines, but it 
needs help in order to communicate with 
off-board devices. The Z80 has address, 
data, and control lines, but it lacks the on- 
chip I/O lines which are on control ori- 
ented processors such as the 8031. 

Peripheral chips are used to convert 
low-level logic signals to the higher levels 
needed for communications and control. 
There are many peripheral chips with dif- 
ferent combinations of characteristics 
available. For this project we will use the 
MAX232 Dual RS-232 Receiver/Trans- 
mitter which is specifically designed for 
RS-232 serial communications. Buffers, 
drivers, latches, opto-islolators, and other 
peripheral chips will be covered in future 
projects. 

Not all peripheral chips are used for 
signal level interfacing. There are also tim- 
ers, counters, communication protocol, A/ 
D and D/A, and many more devices. The 
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Z80 communications gateway uses the 
Z80 SIO, and the Z80 CTC. If we add a 
bidirectional parallel port we'll use the 
Z80PIO. 

RS-232 Serial Communications 

The two methods of communicating 
between boards and/or systems are serial 
and parallel. With serial communications 
the information is sent through one pair of 
wires, one bit at a time, with each bit fol- 
lowing the other. Parallel communications 
uses one wire for each bit, and sends a 
group of bits at the same time. Examples 
of serial communications are RS-232, 
RS422, and RS485. Parallel communica- 
tions is used for the Centronics printer in- 
terface and for computer buses. Addi- 
tional lines are often added for control sig- 
nals. 

Serial and parallel communications 
both have their uses. In general, serial is 
slower because the bits are sent one at a 
time, it takes more software and/or hard- 
ware to support the protocol, wiring costs 
are less because of the fewer wires re- 
quired, and the standard serial implemen- 
tations can handle long distances. Parallel 
is faster because more bits are sent at the 



same time (8 bits at once for Centronics, 
and up to 32 bits at once for some buses), 
it takes less software and/or hardware to 
support the protocol, wiring costs are 
higher because of the large number of 
wires, and the usual implementations are 
intended for shorter distances. 

Communications involves much more 
than just dumping some bits into one end 
of a wire and picking them up a the other 
end. Communications protocol specifica- 
tions can be broken down into two general 
areas. 1) Mechanical and electrical specifi- 
cations, such as how many signal lines, 
voltage levels, connector design, etc. 2) 
Signal definitions, such as the number of 
bits, headers, control signals, timing, error 
detection and correction, etc. While the 
RS-232 interface is widely used, it is far 
from being standardized, and almost every 
manufacturer redefines the signal lines - 1 
have a rack full of adapter cables needed 
to make systems talk to each other. Many 
starting consultants paid the rent by 
trouble shooting RS-232 computer/printer 
interfaces with a breakout box. I'll design 
the gateway to interface with my equip- 
ment with a rather simple protocol. You 
may have to either modify it to work with 
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your system, or else write compatible driv- 
ers for your system. 

The following information is NOT a 
complete tutorial on RS-232-that would 
take a small book. Hopefully, it will be 
enough to get you started. I am consider- 
ing a separate RS-232 tutorial booklet, 
and would like to hear how many people 
are interested. 

RS-232 Electrical and Mechanical 
Specifications 

RS-232 was written for two computers 
talking to each other over telephone lines 
with modems connecting the computers to 
the phone lines. It was intended for a 
DTE-DCE-telephone line-DCE-DTE link 
where each computer (the DTE, or Data 
Terminal Equipment) was connected to a 
modem (the DCE, or Data Communica- 
tions Equipment), and the modems were 
connected to each other by the telephone 
line. The standard is too general, was not 
written with micros in mind, and is unnec- 
essarily complex for most micro applica- 
tions. When designers simplify the stan- 
dard for their application, they don't 
choose the same path. This creates a con- 
fusing mess. 

The RS-232 electrical specifications are 
quite complex. It includes things such as: 
The driver (sending chip) must not be 
damaged by an open circuit or by a 
short to ground or to any other wire 
in the cable. 
The terminator (receiving chip) must be 
able to tolerate 25 volts above ground 
and 25 volts below ground. 
The driver's impedance should be selected 
such that the "one" and zero" levels 
at the output of the driver are be- 
tween 5 and 15 volts in magnitude. 
A logical "one," or MARK or OFF condi- 
tion exists when the voltage at the in- 
terface point is between -3 and -15 
volts. 
A logical "zero," or SPACE or ON condi- 
tion exists when the voltage at the in- 
terface point is between +3 and +15 
volts. 
The RS-232 driver and electrical in- 
clude bipolar (both positive and negative) 
voltages and voltage levels above those 
that TTL logic chips can supply. There are 
standard driver and receiver chips for RS- 
232, and everyone I know uses these chips 
instead of trying to clobber up something. 
The industry standard chips are the 1488 
Quad line driver and the 1489 Quad line 
receiver (49 cents each at Jameco). The 
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driver requires both positive and negative voltages, and is usu- 
ally supplied with + 12 and -12 volts. Most small computer 
boards will run on just +5 volts, except for the RS-232 port, 
and it was aggravating to have to provide +12 and -12 volts 
for the serial port. Maxim developed the MAX232 chip with 
two receiver and two driver channels plus charge pumps which 
runs on just the usual +5 volts and generates +10 and -10 
volts on the chip— you'see this chip used frequently here and 
in Circuit Cellar Ink. Motorola has recently announced the 
MC145407 5 volt only Driver/Receiver with three drivers and 
three receivers. I've been told that on occasion the Maxim 
chip lacks the power to drive long lines, and in these cases the 
Motorola chip has provided enough power to solve the prob- 
lem. 

The standard defines 25 pins, three of which are unas- 
signed and two of which are reserved for testing (see Figure 
2), but does not specify the size or shape of the connector. For 
a long time the de facto standards were the DB-25S (female) 
and DB-25P (male connectors. IBM uses a non-standard nine 
pin DE9 connector for the serial port and an DB25 for the 
parallel port. Some manufacturers have put both a serial and 
a parallel port on a single DB25 connector, while others have 
added a current loop interface to an RS-232 DB25 
connector— you'll have to watch out for non-standard bastard 
implementations. 

You really need the RS-232 specifications for any com- 
puter, terminal, printer, or other device with which you want 
to communicate. My Morrow Decision I S-100 systems are 
non-standard, and I had to learn a lot about RS-232 before I 
could ge' them to communicate. The Ampro Z80 Little 
Ejluu (which is now again available, see editorial), is more 
standard, using six wires (Protective Ground, RXD, TXD, 
RTS, CTS, and Signal Ground). 

The minimum for two way RS-232 communications is 
three wires with Signal Ground, RXD, and TXD, which is 
what is provided on most controller processors. 

The formal name of the RS-323 is Interface between Data 
Terminal Equipment and Data Communications Equipment 
Employing Serial Binary Data Interchange. It describes, 1) The 
mechanical description of interface circuits, 2) The functional 
description of interchange circuits, 3) The electrical signal 
characteristics. It does not specify the ASCII character set or 
how to control message transfer using ASCII. We need a new 
up-to-date standard, one author has referred to RS-232 as 
death throes of a dinosaur. But RS-232 is what we have, and 
we'll have to make it work. 

Serial Binary Data Transfer using a UART 

The subject of data transfer is entirely separate from the 
subject of RS-232, although we usually consider them as one 
and the same. But RS-232 only describes the lines and volt- 
ages, it doesn't specify what is being sent. A full discussion of 
start bits, data bits, stop bits, and parity would take most of 
TCJ. We'll leave that to the bit-bangers for now, and use the 
Z80 SIO UART (Universal Asynchronous Receiver Trans- 
mitter) which does most of the hard work for us. The SIO is 
configured by writing to certain registers during system initiali- 
zation, and then the parallel data is sent to and received from 
the SIO. 

The SIO BAUD rate (used in honor of a Frenchman 
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named Baudot) is determined by the combination of the receiver and 
transmitter clock signals and the clock mode. The Z80 CTC Counter/ 
Timer is used to provide programmable clock rates for the SIO. 

Next Time 

So far we have concentrated on the fundamentals. Next time well 
cover the details of the Z80 SIO and CTC, and how they are used for 
RS-232 serial communications. If you have any questions or comments 
on RS-232 or serial communications, send them for use in this col- 
umn. • 
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Advanced CP/M 

Tuning JetFind 

by Bridger Mitchell 



Trenton Computer Festival Notes 

This year, the 15th annual Trenton Computer Festival featured 
an all-day Saturday section on current and future Z-System devel- 
opments. Coordinated by Jay Sage, the program included: 

10:30 Bridger Mitchell: Tools for CP/M - DosDisk, JetFind, 

PluPerfect Writer, and the new ZMATE editor. 
1 1:45 Bob Todd: SIG/M: Future of Public Domain Software. 
1:00 Jay Sage: Introduction to Z-System. 
2:15 Hal Bower, Cam Cotrill: The Future of 8-Bit Operating 

Systems. 
3:30 Jay Sage: Computing Automation Using ARUNZ 

Scripts. 
4:20 Al Hawley: Assembly Language Programming and the 

New ZMAC Assembler. 
4:45 Bridger Mitchell: Multitasking with BackGrounder ii. 

Despite the heavy rains on Saturday, it was standing room only 
for several talks, and conversations continued well into the morn- 
ing hours of Sunday. Then it was catch a few winks and off to the 
flea market. 

' As a first -time attendee I particularly enjoyed meeting so many 
talented Z-System colleagues face to face! Cam Cotrill, Al Hawley 
and Rob Friefeld also came from Los Angeles, and Carson Wilson 
from Chicago. Others, from up and down the East Coast, included 
Lee Bradley, Howard Goldstein, Liv Hinckley, Chris McEwen, 
Bruce Morgen, Dick Roberts and Bob Schultz. If you missed 
Trenton, look out for Tony Parker's "z-system, lies, and vide- 
otape"! 

Tuning JetFind 
Computers are good for organizing information -or at least 
they should be! It's easy enough to save correspondence, notes, 
old programs, addresses and most everything else that clutters up 
a real desk in files on disks. The files can have somewhat meaning- 
ful names, and related files can be stored together in library files. 

Bridger Mitchell is a co-founder of Plu*Perfect Systems. He 's the 
author of the widely used DateStamper (an automatic, portable file 
time stamping system for CP/M 2.2); Backgrounder (for Kaypros); 
BackGrounder ii, a windowing task-switching system for Z80 CP/M 
2.2 systems; JetFind, a high-speed string-search utility; DosDisk, an 
MS-DOS disk emulator that lets CP/M systems use pc disks without 
file copying; and most recently Z3PLUS, the ZCPR version 3.4 sys- 
tem for CP/M Plus computers. 

Bridger can be reached at Plu*Perfect Systems, 410 23rd St., 
Santa Monica CA 90402, or at (213J-393-6105 (evenings). 



And disk space can be reduced by crunching or squeezing the files 
first. 

The rub comes when you need to retrieve some of that infor- 
mation. Much of the time I can't remember exactly which file I 
saved it in. And in many cases I need only a few lines of material 
buried inside the file. Or, I may be looking for a particular subrou- 
tine or data structure. 

Some three years ago I looked into the programs available to 
handle these retrieval tasks. Dissatisfied with them all, I wrote 
JetFind, a tool that can find one or several strings in files. 

Three things set JetFind apart. First, it works with most types 
of CP/M files -text, WordStar, crunched, squeezed, and also any 
of those types when stored a library. Second, it has very powerful 
"wild-card" capability and can match regular expressions. And 
third, it is fast, so fast that many users find it more convenient to 
search for information by running JetFind than to reach up to 
their bookshelf for documentation that is near at hand. Compara- 
tive testing by others has established that JetFind is some two to 
six times faster than other Z80 search tools. 

String Searches 

Searching for strings is one of those programming tasks that 
presents itself as a really standard, top-to-bottom problem, one 
that almost automatically organizes itself into logical blocks. Once 
you have obtained the search parameters from the user, your pro- 
gram's tasks are: 

open a file 
read a block 

move a line into linebuffer 
scan line for pattern 

if found, report success 

In each task block, the task is repeated until a termination 
condition is encountered ("while more files", ..., "while another 
pattern"). Like the poet's fleas, a smaller task is perched on the 
shoulders of its surrounding task block. Indeed, if we look inside 
the scanning block, it too has still smaller "while" loops. 

With this strong hierarchy governing the search, it's pretty clear 
that there are big payoffs to tuning the innermost task -the line 
scanner that matches a pattern. And, indeed, a better pattern- 
matching algorithm proves to be a better mousetrap. 

What is not so obvious, perhaps, is that simply getting a byte of 
input from a file is also a place where major speed can be gained. 
In developing JetFind I had paid a good deal of attention to both 
areas, and achieved some significant speedups over the "obvious" 
hierarchy. 
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A New Burst of Speed 

Despite JetFind's good performance, since com- 
pleting the distribution version three years ago I've 
occasionally wondered if I had overlooked some op- 
portunity for still-faster searching. And I've kept 
watch on some of the computer science literature 
that covers efficient searching algorithms. 

Recently, two papers caught my attention. An- 
drew Hume, (in the November 1988 
Software— Practice and Experience) describes his 
success in speeding up two UNIX versions of 'grep'. 
Using a profiler, he isolated time-intensive sections 
of the code. Replacing the standard C input/output 
library functions more than tripled the speed of 
grep. That result didn't surprise me; in JetFind I had 
worked hard to optimize the file input routine, and 
had already won substantial gains. But his second 
optimization held still unrealized potential for 
JetFind - using a variant of the "Boyer-Moore" 
algorithm. 
Smart Searching 

Everyone knows how to search for a pattern by 
"brute-force." You start at the beginning of the line 
and compare the first byte with the first byte of the 
pattern. If they match, compare the second bytes, 
etc. If all pattern bytes match, the search succeeds. 
If not, point at the second byte of the line and re- 
start the pattern comparison. 

In 1977 {Communications of the ACM, October) 
Boyer and Moore published their key idea— start 
comparing at the end of the pattern, and work back- 
ward toward the first byte. Then, when a mismatch 
occurs, move forward as far as possible and then 
again compare from the end of the pattern. 

The Boyer-Moore algorithm works like this. Sup- 
pose we are searching for the word "where". It has 5 
characters, one of which is repeated. We make the 
first check at position 5 of the line, comparing the fi- 
nal pattern letter, an 'e', with the letter at that posi- 
tion in the text being searched. 



text: 

pattern : 



12 3 
v h e 
w h e 



4 5 6 7 8 9 







Figure 1 . Sketch of Boyer-Moore Algorithm in Z80 Code. 
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Figure 2. Initializing the Displacement Table 
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If it is 'e', we check the previous character for a match with 
'r'. And we continue checking from right to left until either we 
have matched all 5 characters and found an instance of the 
pattern (shown above) or we have a mismatch. 

Most of the time a mismatch occurs, and then we jump 
ahead, by sliding the pattern to the right as far as possible. 

1234567890 
text: everywhere 

pattern: where 

How far can we slide? Suppose, first, that the first text 
character that we check (a y") doesn't occur anywhere in the 
pattern. In this case we can slide the pattern 5 characters to 
the right, the length of the pattern. 



Why? Because now that we know that the pattern cannot be found 
in the first 5 characters of the text because they include something not 
in the pattern. 

Suppose, instead, that the first character we check (a *w') does occur 
in the pattern, but not as the last character. 



text: 
pattern : 



12 3 4 5 6 7 
now w h e 
where 



Then we can slide the pattern to the right far enough to align that 
position in the text with the pattern, and then again start checking from 
the right end of the pattern. (In this case we slide right by 4 characters). 



text: 
pattern : 



12345678 
now w h e r 
. . . . w h e r 



text: 
pattern : 



123456789 
everywher 



where 



Boyer-Moore is a kind of leap-frog algorithm. It has the directness 
and impact of a light-bulb-just-turned-on, why-didn't-I-think-of-that! 
An idea that is "obvious" in retrospect, and a contribution you will 
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always admire. 

Unfortunately, the details aren't equally direct. The algorithm 
and several variations have been studied in considerable depth in a 
succession of computer science papers. A number of actual imple- 
mentations have also been described. 

The second article I had spotted, in the July 1989 issue of Dr 
Dobbs' Journal, claimed a major improvement in search speed 
implementing the Boyer-Moore method under MS-DOS Tur- 
.boPascal. But on closer investigation a reader had found (DDJ, 
October 1989) that particular code proved to be slower than brute 
force coded in the same language! 

Nevertheless, I kept returning to the Boyer-Moore algorithm in 
idle moments, feeling there must be some way to exploit its inher- 
ent efficiency. And ultimately I found it. 

The Z80 Algorithm 

For this implementation I could assume that the text to be 
searched was a line already in a buffer and not more than 254 
bytes long. I put the pattern in a second buffer and arranged the 
buffers so that both begin on "page" (nnOO hex) boundaries. 

Look at Figure 1. The heart of the search is quite elegant. 
Short, quick instructions manipulate the low byte of the pattern 
and text pointers. 

The major piece missing from Figure 1 is the displacement 
table that tells the algorithm how far to shift the pattern, or 
equivalently, how many characters may be jumped over. Figure 2 
gives a simple routine for initializing it. First, all displacements are 
set to the length of the pattern, pretending that each of those 
characters does not appear in the pattern anywhere. Then, for 
each character that does appear in the pattern, the displacement is 
"corrected" to be the distance from that character to the end of 
the pattern. 

Because this "correction" value is computed from left to right, 
it will never be too large and cause the jump to skip past a true 
match. In some circumstances, however, it results in a smaller than 
optimal jump. The optimal algorithm been worked out, but it is 
more complicated and also increases the number of instructions in 
the innermost comparison loop. The simple correction algorithm I 
used is, I believe, due to Horspool (1980 Software— Practice and 
Experience). 

Actual Implementation 

Getting a search algorithm working in a real program requires 
paying attention to a host of other details. You have to initialize 
the pointers and line length before you can use the routine. And of 
course, you have to have all of the surrounding code from the 
higher-level blocks, as well as the user interface, to specify the 
patterns, files, and options. In all, JetFind is some 16K. 

Moreover, it sometimes pays to look before you leap-frog with 
Boyer-Moore. You can scan the line for the first occurrence of the 
final character of the pattern, using the zippy Z80 CPIR instruc- 
tion. This quickly rules out many lines that don't contain the pat- 
tern, and gets the search started well into the line for others. How- 
ever, because this involves inspecting each character, it can be less 
efficient than using just the Boyer-Moore search when the pattern 
is more than a few bytes long. 

The new version of JetFind checks to see if the pattern is a 
"plain" pattern, or includes one or more wild-card characters that 
make up a general regular expression. If it is plain, it uses the 
Boyer-Moore algorithm. If not, it uses the already developed 
"grep" algorithm. 

There's one other point of some interest. When a crunched file 



is processed, some of the logic is inverted. You might think that 
uncrunching would simply involve adding an "uncrunch-block" 
task between steps 2 and 3. And it could be done that way. But 
decompression is inherently a variable-flow process: you read 
some bytes and bits and produce some, or perhaps quite a few 
more, as output. So, instead of managing a variable-sized buffer 
for the uncrunched output, it is more convenient to invert the 
process. The uncruncher takes control, reading blocks and calling 
the pattern-scanner for each line, until the file is fully processed. 
By maintaining well-modularized routines, it was possible to intro- 
duce this change in flow with very little recoding. 

open a file 
call uncruncher 
read a block 
uncrunch a line 
move line into linebuffer 
scan line for pattern 
if found, report success 

Performance 

The theoretical performance of the Boyer-Moore algorithm is 
impressive. It's worst-case running time is proportional to the 
number of bytes in the input text ("linear"), and its average time is 
less than proportional ("sub-linear"). 

To get an approximate measure of the improvement obtained, 
I ran the old and new JetFind versions on the source files (147K in 
all), using timing to the nearest second that is automatically re- 
ported by JetFind when running on a DateStamper system. 

For this test the basic overhead to read the files was 5 seconds 
on an SB180FX's ram disk (at 9 MHz, 1 wait state). Searching for 
four identical patterns ("expression") , JetFind version 1.22 re- 
quired an additional 7 or 10 seconds, depending whether case fold- 
ing was requested when it used the "grep" algorithm. Using the 
Boyer-Moore algorithm, the extra time was just 2 or 3 seconds. A 
single pattern can be searched in essentially the time required to 
read the files! 
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Other Search Algorithms 

The search for a still more efficient search (!) has occupied 
more than a few good minds, and there is a growing literature on 
variants of Boyer-Moore and other algorithms. Significant gains 
can be achieved for special cases such as small alphabets and large 
memories. The vanilla Boyer-Moore, however, is likely to remain 
the speed leader for general-purpose string searching. • 
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Animation With Turbo C Ver. 2.0 

Part 2: Screen Interactions 

by Clem Pepper 



. Before beginning new topic I must back up a couple issues to 
make a correction. I hereby apologize for any frustration resulting 
from my omitting the variable declarations from some programs in 
the March/April issue. Also, after emphasizing the use of 
HEADING.C I am replacing it with a superior approach. The 
programs I am referring to are RECT1.C, PLANE.C, TANK.C 
and VIEWPORT.C. Listing 1 contains the revised declarations. 

Listing 2 is an include file, GRAP_ENB.H. Its use is illustrated 
in the revisions of Listing 1. All the required function calls for 
enabling the graphics mode are included in this file. The palette 
number is declared in the program file and passed to 
GRAP_ENB.H in the function call enablejgraph(palette);. Wish 
I had thought of this at the beginning, it is so much cleaner. 

Taking Advantage Of Turbo C's MAKE Utility 

In this segment of the series on animation we are taking our 
initial step toward the production of a complete screen action 
game. This portion of the game consists of five modules. The five 
require compiling and linking to acquire the .EXE run file. Nor- 
mally when in the process of developing a project of this scope I 
give each of the modules its own main() so it can be compiled and 
run independently. Using that approach with this number of mod- 
ules in an article series is impractical, so we sort of have to dive 
right in. 

It's not all that bad. Learning to use MAKE straight out of the 
Borland manual can be frustrating; it took me the better part of 
three evenings to make sense of it. So you're getting the benefit of 
my frustrations— be happy. 

MAKE really makes compiling and linking modules easy and 
fast. The MAKE file for the game we are going to learn about 
here is shown in Listing 3. The top line of the listing is where the 
action all comes together at the finale. It defines the .EXE file as 
the end product of the module .OBJ files. The next line calls 
TLINK for the module linking at the .OBJ level. This instruction is 
spread over two lines as a necessity for printing. It MUST ALL BE 
ON ONE LINE in your .MAK file. The lines below perform the 
compiling of the individual C modules. The sequence doesn't mat- 
ter, though I normally place the module containing main() at the 
bottom. 

My name for this file is TNK_WAR.MAK You can call it by 
any name you choose so long as the extension is .MAK The com- 
mand line must read MAKE -FTNK_WAR (in my case). Without 
the leading -F the program will abort. 

You may very well need to make changes from the listing. I do 
all my work on a floppy in drive A. My Turbo C files are on a hard 
drive, directory E:\btc20, E:\btc20\include, and E:\btc20\lib. My 
AUTOEXEC includes a path statement of: 

PATH«C : \PCWRT;E : \BTC20 



Listing 1 . Corrections to the previous graphics program listings. 

************ 

RECTI. C 

I include <stdio.h> 
t include <graphics.h> 
finclude "grap_enb.h" 

/* ■■ Begin prograa ■■ */ 
main( ) 

{ int palette » 2; /* specify 0,1,2, or 3 */ 
enable_graph( palette) ; 

I 
pick up from article listing. 



PLANE.C 

finclude <stdio.h> 
finclude <graphica.h> 
f inc lude " gr ap_enb . h " 

/* ■■ Begin program ■■ */ 
main( ) 

{ int palette * 2; /* specify 0,1,2, or 3 */ 
enable_graph( palette) ; 

I 

pick up from article listing. 

************ 
VIEWPORT.C 
finclude <stdio.h> 
finclude <graphics.h> 
finclude "grap enb.h" 

/* » Begin program ■■ */ 

main ( ) 

{ int palette "2; /* specify 0,1,2, or 3 */ 

int i - 9, left_col - 0; rite_col ■ 9, top ■ 0, bottom "9; 
enable_graph(palette) ; 

I 

pick up from article listing. 

************ 
TANK.C 

f include <stdio . h> 
finclude <graphics.h> 
finclude "grap_enb.h" 

/* -» Begin program -• */ 
main( ) 

{ int palette ■ 2; /* specify 0,1,2, or 3 */ 
enable_gr aph ( pa lette ) ; 



I 

pick up fron article listing. 



Because I am still using MS-DOS 2.11 only .EXE files are identi- 
fied. So I copy C0S.OBJ, TURBOC.CFG and GRAPHICS.LIB 
onto the floppy. So you must modify your MAKE file to conform 
to your system. 

To use the MAKE utility with the five modules all that is neces- 
sary is to type up the .C source files. With this done simply enter 
make -ftnk_war on the command line, press the Enter key, sit 
back and enjoy the clicking as your hard disk and floppy go 
through the process of compiling and linking the modules. The 
real beauty of it is when you make a change in one of the modules. 
MAKE identifies the changed module by comparing the time and 
date on the source and object files. Really neat! 
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Listing 2. The header file for enabling the graphics mode. 

/* GRAP_ENB.H 

** Call this function with the main() nodule of * graphics program. 



/* -■ enable the graphics node ■■ */ 
enable_graph ( int graphmode ) 



int graphdriver ■ CGA; 
int errorcode; 



/* graphics driver */ 
/* graphics error code */ 



initgraph(&grapbdriver, (graphmode, "e: \\btc20") ; 

/* ** replace "e:\\btc20" with your directory location ** */ 
errorcode - ( graphresult ( ) ) ; /* get result code * / 

/# #* graphics error function routine call ** */ 
if (errorcode !- grok) /* always check for error */ 

{ 

printf ( "Graphics error: %e\n",grapherromeg(errorcode) ) ; 
exit(l); 
> 

/* ** call to set background color ** */ 
setbkcolor(BLUE) ; 



Listing 3. The Turbo C MAKE file for TANK_WAR.C. 

tankjwar.exe: tank_war.obj bonr.obj shell. obj gne_figs.obj bombs. obj 
tlink cOs bombs gme_figs shell bonr tank_war , tank_war , /x , 
e:\btc20\lib\ca graphics. lib Hote: This MUST all be on one 
line. 

bonbs.obj: bombs. c 

tec -a -c -u bombs. c 

gme_figs.obj : gme_figs.c 
tec -a -c -ms gme_figs.c 

shell. obj: shell. c 

tec -a -c -ns shell. c 

bonr.obj: bonr.c 

tec -a -c -ns bomr.c 

tank_war . ob j : tank_war . c 
tec -a -c -ns tank war.c 



The Basics of Module Construction 

The five modules of Listings 4 - 8 are printed with line num- 
bers. This to make it easier for me when referring to a specific 
function or whatever in any given module. 

Starting at the top we observe that each module contains only 
those #include files required for itself. The primary module, 
TANK_WAR.C is loaded with the most, seven. The majority of 
the remainder have only one or two. A mandatory #include 
<graphics.h> is found in each. The other is <stdio.h>, required 
when we use some of the keyboard and console functions. 

There are a lot of global declarations. The preferred technique 
with C is to pass values in function calls, but this gets out of hand 
quickly in this kind of a program. So we take the easy way out. 

When a module requires a unique variable that will be used by 
one or more of the other modules it is declared in the originating 
module in the usual fashion as a global int or char or whatever. In 
those modules making reference to that variable the declaration is 
preceded by extern. This informs the compiler, TCC, that the vari- 
able is declared somewhere else. We don't have to be specific on 
where somewhere else is, the compiler will track that down on its 
own very nicely. 

To be fair I should mention I do all my work with my own 
editor, PC- Write and the command line. I almost never use the 
environment file, TC. That should not in any way effect the results 
obtained with TANK_WAR as shown in the listings. 

In one respect the modules are rather sloppy in that I have not 
been too concerned with function prototypes. If you want to work 
them in, feel free. 



Listing 4. The main module for the TANKWAR action game. 



/* TAHIC_WAR.C 

** Main nodule for TAHK_HAR screen action game. 

** Compiled with TURBO C Ver. 2.0 graphics library routines. 

** 

*/ 

I include <stdio.h> 
tinclude <conio.h> 
tinclude <alloc.h> 
# include <ctype.h> 
I include <doa.h> 
# include <graphics.h> 
tinclude "grap_enb.h" 
tdefine SPKBY 0x16 
extern void clr_bomrs(); 

/* ** global declarations ** */ 
int n_asc, ion; 

int leftt_eol - 200, ritet_col - 219; 
int tdir_£lg - 0; /* tank moves to left */ 
extern char far *tank; 
extern int bhl_hit,bh2_hit,bh3_hit; 

/* ■- read non-ascii key »« */ 
int rd_nonaeky ( ) 



union REGS regs; 
regs. h. ah "0; 
regs.h.al "0; 
int 86 ( SFKEY . (regs , 
n_asc - regs . h . ah ; 



dregs ) ; 

/* non-ASCII code 



/ 
sen - regs.h.al; /* SCAN/ASCII code */ 



) 

/* -- Begin program -- */ 
main() 

{ 

int palette ■ 2, i - 1; 
char key, run "0; 
enable_graph( palette) ; 
/* ** create game figures ** */ 
drw_fige(); 
/* ** set viewport for scoring ** */ 

/* This will be added later */ 
/* ** begin animation ** */ 
while (i) { sen ■ 1; 
/* ** tank direction on screen control ** */ 
if(tdir_flg -- 1) { 

leftt_eol +- 3; ritet_col +- 3; 

> 
else if(tdir_flg — 0) 
{ leftt_col -- 3; ritet_col -- 3; } 
draw_tank(>; 
/* ** increment bomber group ** */ 
bomberO; 

if(bhl_hit -- j j bh2_hit — || bh3_hit -- 0) 
drop__bombs ( ) ; 
shel(run); run - 0; 
drop_bombs ( ) ; 
clr__bomrs ( ) ; 
putimage ( lef tt_col ,189, tank , XORJPUT) ; 
if(leftt_col <- 4) { tdir_£lg - 1; continue; > 
if(ritet_col >■ 297) { tdir_flg - 0; continue; > 
/* ** obtain input from the keyboard ** */ 
if(kbbit() ■■ 0) continue; 
rd_nonasky ( ) ; 
if(n_asc --72 || n_asc — 75 || n_asc — 77) goto L; 
else { run - toupper(toascii(Bcn) ) ; 
if (run — *Q') { i - 0; break; } 
else if (run « 'A' | | run « 'S* | | run « ' * 
| | run -- ' D ' || run ™ ' F ' ) continue ; 
} 
/* ** move tank to the right ** */ 
L: if(n_asc « 77) 

{ tdir_flg - 1; continue; > 
/* ** move tank to the leftt ** */ 

else if(n_asc « 75) { tdir_flg - 0; 
continue; } 
/* ** halt tank in current position ** */ 

else if(n_aac « 72) { tdir_flg - 2; 
continue; } 

) 

closegraph( ); /* return to text mode */ 

exit(0); 

} 

/* « draw tank as sequence of horiz lines -- */ 
draw_tank ( ) 

{ 

put image ( lef tt_col ,189, tank , COPY_PUT ) ; 



As you scan through the listings take note of the large number 
of comments. Getting lost in the maze of program interactions 
between modules is no problem at all. In your modules comment 
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Listing 5. The TANKWAR game 


module for play object construction. 


1 


/• SME_FISS.C 


69: 


bomr " (char *) ma Hoc (numbytes) ; 


2 


** Game figure creation module for TANK WAR game. 


70: 


getimage(0,0,20,20,bomr) ; /* save the image */ 


3 


** Conpiled vith TURBO C Ver. 2.0 graphic library routines. 


71: 


cleardevice ( ) ; 


4 


«/ 


72: 


/* ** drav shell figure " */ 


5 


# include <alloc.h> 


73: 


/* ** as a sequence of vert lines ** */ 


6 


# include <graphics.h> 


74: 


setlinesty le (0,0,1); 


7 


/« «» global declarations ** */ 


75: 


setcolor(3); /* brown */ 


8 


char far *tank; 


76: 


moveto(0,2); lineto(0,5); 


9 


char far *bomr; 


77: 


moveto(l,0); lineto(l,6); 


10 


char far 'shell; 


78: 


moveto(2,2); lineto(2,5); 


11 


char far *burst; 


79: 


/* ** determine storage needed ** */ 


12 


char far *bomb; 


80: 


numbytes ■ (unsigned int)imageaize(0,0,6,6) ; 


13 


/* »■ begin program *« */ 


81: 


/* ** allocate buffer ** */ 


14 


drw figs ( ) 


82: 


shell ■ (oner *)malloc(numbytee) ; 


IS 


{ 


83: 


getimage(0,0,6,6,sbell) ; /* save the image */ 


16 


char buffer[80]; 


84: 


cleardevice ( ) ; 


17 


unsigned numbytes; 


85: 


/• ** drav burst figure « */ 


IS 


/* ** draw initial tank figure ** */ 


86: 


/* ** as a sequence of lines ** */ 


19 


setlinestyle(O f 0, 1) ; /* solid line, one pixel vide */ 


87: 


setcolor(2); /* red */ 


20 


setcolor(2); /* tank top is red */ 


88: 


setlinesty le (0,0,1); 


21 


moveto(9,0); lineto( 15,0) ; /* segment a */ 


89: 


aoveto(4,4); lineto(4,7); 


22 


setlinestyle(0 f 0,3 } ; /* solid line, 3 pixels vide */ 


90: 


moveto(5,4); lineto(5,6); 


23 


moveto(7,2); lineto(17,2) ; /* segment c */ 


91: 


moveto(6,3); lineto(6,7); 


24 


setlinestyle(0,0, 1) ; /* solid line, one pixel vide */ 


92: 


moveto(7,4); lineto(7,6); 


25 


moveto(9,4); lineto(15, 4) ; /* segment d */ 


93: 


setcolor(3); /* brown */ 


26 


setcolor(l); /* lover tank is green */ 


94: 


moveto(2,5); lineto(3,4); 


27 


moveto(5,5); lineto(19,5) ; /* segment e */ 


95: 


linerel(l.-l); linerel(l.O) ; linerel(l.-l) ; 


28 


moveto(4,6); lineto(19,6) ; /* segment f */ 


96: 


linerel(l,0); linerel(0,l) ; linerel ( 1 , 1 ) ; 


29 


moveto(5,7); lineto(19,7) ; /* segment g */ 


97: 


linerel(l,l); linerel (-1,1) ; linerel (-1,1) ; 


30 


moveto(6,8); lineto(18,8) ; /* segment h */ 


98: 


linerel(-l,l); linerel ( -1, -1 ) ; linerel(-l,l) ; 


31 


moveto(7,9); lineto(17,9) ; /* segment i */ 


99: 


linerel (-1,-1); linerel ( -1, ) ; linerel ( 1, -1 ) ; 


32 


/* ** determine storage needed ** */ 


100 


: linerel (-1,-1); 


33 


numbytes " (unsigned int) imagesize( 0, 0, 20,20) ; 


101 


: setcolor(l); /* green */ 


34 


/* ** allocate buffer ** */ 


102 


: moveto(0,3); lineto(l,l); 


35 


tank ■ (char far * )malloc(numbytes) ; 


103 


: linerel(l,l) ; linerel(l,-l) ; linerel(0,-l) ; 


36 


getimage(0, 0,20, 20, tank) ; /* save the image */ 


104 


linerel (-1,-1); linerel (1,0) ; linerel(l, 1) ; 


37 


cleardevice( ) ; 


105 


: linerel ( 1 , ) ; linerel ( 0,-1) ; linerel ( 1, -1 ) ; 


38 


/* ** draw initial bomber figure ** */ 


106 


: linerel (1,1) ; linerel (1,0) ; linerel (1,1) ; 


39 


setcolor(2); /* fuselage is red */ 


107 


: linerel (-1,1); linerel (1,1) ; linerel ( 1, 1) ; 


40 


/* ** drav vings ** */ 


108 


: linerel (-1,1); linerel ( , 1 ) ; linerel (-1, 1) ; 


41 


setcolor(l); /* vings, tail are green */ 


109 


: linerel(-l,l); linerel ( 0, 1 ) ; linerel ( -1, -1 ) ; 


42 


moveto(9,l); lineto(9,8); /* segment wl */ 


110 


: linerel(-l,-l) ; linerel(-l,l) ; linerel(-l, 0) ; 


43 


moveto(10,2) ; lineto(10,8) ; /* segment w2 */ 


111 


: linerel(0,-l) ; linerel(-l,0) ; linerel(-l,-l) ; 


44 


moveto(ll,3) ; lineto(ll,8) ; /* segment w3 */ 


112 


: linerel(l,-l); linerel(-l,-l) ; linerel ( 0, -1 ) ; 


45 


moveto(12,4) ; lineto(12,8) ; /* segment w4 */ 


113 


: linerel(-l,-l); 


46 


moveto(13,5) ; lineto(13,8) ; /* segment w5 */ 


114 


: putpixel(7,8,3) ; putpixel(8,7,3 ) ; 


47 


moveto(14,6); linetof 14, 8) ; /* segment w6 »/ 


115 


: putpixel (8,2,3) ; putpixel ( 6,1,3) ; 


48 


moveto(14,12); lineto( 14 , 14 ) ; /* segment w7 •/ 


116 


: putpixel(2,3,3); putpixel ( 1,2,3 ) ; 


49 


moveto(13,12) ; lineto( 13 , 15) ; /* segment v8 */ 


117 


: putpixel (3, 5,3); putpixel (8, 5, 3) ; 


50 


moveto(12,12); lineto( 12 , 16 ) ; /« segment v9 »/ 


118 


/* ** determine storage needed ** */ 


51 


moveto(ll,12); lineto( 11, 17) ; /* segment wlO */ 


119 


: numbytes * (unsigned int)imagesize(0,0,10, 10) ; 


52 


moveto(10,12) ; lineto( 10, 18) ; /* segment wll */ 


120 


: /« •• allocate buffer »« »/ 


53 


moveto(9,12) ; lineto(9, 19) ; /* segment wl2 */ 


121 


: burst * (char *)malloc(numbytes) ; 


54 


/« »* draw tail »» »/ 


122 


: getimage(0, 0,10, 10, burst) ; /* save the image */ 


55 


moveto(l,5); lineto(l, 15) ; /* segment si */ 


123 


: cleardevice ( ) ; 


56 


moveto(2,5); lineto(2, 15) ; /* segment s2 */ 


124 


: /* ** draw bomb figure ** */ 


57 


moveto(3,6); lineto(3,14 ) ; /* segment s3 */ 


125 


: setcolor(2); /* red */ 


58 


moveto(4,7); lineto(4 , 13 ) ; /* segment s4 */ 


126 


: setlinestyle(0,0,l) ; 


59 


/* ** draw fuselage ** */ 


127 


: putpixel (0,0, 2) ; putpixel (2, 0,2) ; 


60 


setcolor(2); /* fuselage is red */ 


128 


: moveto(0,2); lineto(0,5); 


61 


moveto(8,8)i lineto(15, 8) ; /* segment fl */ 


129 


: moveto(l,0); lineto(l,6); 


62 


moveto(4,9); lineto( 18,9) ; /* segment f2 */ 


130 


: moveto(2,2); lineto(2,5); 


63 


noveto(0,10); lineto(20,10) ; /* segment f3 */ 


131 


/* ** determine storage needed ** */ 


64 


moveto(4,ll) ; lineto(18, 11) ; /* segment f4 */ 


132 


numbytes » (unsigned int)imageaize(0,0,2,6) ; 


65 


moveto(8,12); lineto(15, 12) ; /* segment f5 •/ 


133 


/» »* allocate buffer *• »/ 


66 


/* ** determine storage needed ** */ 


134 


bomb ■ (char * )malloc( numbytes ) ; 


67 


numbytes * (unsigned int)imagesize(0,0,20,20) ; 


135 


get image (0,0, 2, 6, bomb); 


68 


/* ** allocate buffer »• */ 


136 


cleardevice ( ) ; 






137 


> ) 



freely. You'll be awfully glad you did. 

So, let's look at what we have here for a game. 

A Review of the TANK.WAR Action Game 

As mentioned, there are five modules. At this point scoring is 
not included. That will come with the next in this series. 

The TANK.WAR Module 

This module, which contains main(), controls the action. The 
initial step of course is to set up the graphics mode. The second is 
the creation of the game's play objects. These are a fleet of 
bomber aircraft, organized in a flight group of three. There is an 
army tank, which is under control of the player. The player fires 
shells at the planes, so there has to be construction for these. And 
the planes drop bombs on the tank— a construction is in order 
here. When a shell or bomb makes its bang there is need for a 
burst. All of these are constructed in a dedicated module, 



GME_FIGS.C. 

With the play objects all constructed and safely tucked away 
into buffers awaiting the call to action we can begin the screen 
activity. This commences with the while() loop beginning at line 
42. The entire action of the game is controlled by this loop. The 
while is enabled by the integer "i" whose value is set to "1" in the 
declaration. To exit the game this variable is reset, that is, set to 
zero. Another key variable is run, which we will learn more of 
shortly. 

As we take a look at the activity maintained by the loop it 
should become apparent why a loop is the only sensible approach 
to control of the game action. A point of importance is that only 
two actions are available to the player: control of the tank's direc- 
tion and control of its gun firing. And so we have to look at the 
loop as the carrying out of two tightly related tasks: a continuation 
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of the screen action while enabling the player's input on the tank's 
operation. 

In the normal development of a game of this kind operations 
are built up in layers as it were. First came the tank, followed by 
the bomber group. After working out the wrinkles, shell firing was 
added to the tank's activity. With the player able to fire shells 
means had to be developed to detect contact with any of the air- 
craft. A shell burst replacing both the shell and the target was 
designed. With sound. The bombers were taught when to drop the 
objects which would detonate on contact with the tank or the 
"ground." Once a bomb is dropped it has to be maintained, no 
matter what else goes on. All of this activity is reflected in the 
procedures embedded in the while loop. 

As we review the other modules it will become very clear that 
the decision making is heavily dependent on the values taken on by 
flags. Flags are set and cleared as the action requires. The flag 
value becomes the basis for decisions on the kind of action to be 
taken. Right off in the loop we see this process in determining the 
direction the tank is to take in its trek across the screen. Three 
possibilities exist: move left, move right, or don't move at all. We 
will see at the end of the loop how the flag values are arrived at. 

Which should raise the question of why the determination is 
made at the end of the loop. Why not at the beginning. 

Okay. In order to get the game going in the first place some 
arbitrary decisions have to be made, one of them on the direction 
to be taken by the tank. The direction flag is tdir_flg, declared as a 
global integer with the initial value of 0. The tank will start off 
moving to the left. Not too illogical considering its initial 
coordinates, int leftt_col = 200, ritet_col = 219;, also a global, 
place it at the extreme lower right corner of our screen. 

With the tank underway the program now must set the remain- 
der of the agenda into motion. This it does with a call to bomber() 
(line 51). bomber() is located in another module, BOMR.C. Each 
call to bomber() must perform a routine of tasks. These we will 
look at shortly. 

The first check is to ascertain there really is a bomber available. 
A non-existent bomber should not be dropping bombs. If any of 
the hit flags still read zero there really is one available. In this event 
a call is made to a function by name drop_bombs() (line 53, 
TANK_WAR.C). drop_bombs() is in its own module, BOMBS.C, 
Listing 7. Offhand dropping a bomb might appear to be a rela- 
tively simple task. Well, read on and see. 

The call to shel(run) passes information on whether a shell has 
been fired, and if so at which angle. The shell firing keys are the A 
S, D, and F. The test is performed at the SHELL.C module, List- 
ing 8. If no key has been pressed the function returns. If a key has 
been pressed run is reset on the return. 

Line 55 is a second call to drop_bombs(). The purpose here is 
to speed up the descent. Bombs are dropped incrementally unlike 
shells which streak off at their target without interruption. 

At this time, line 56, the bombers are cleared. Recall that the 
call to display the bombers was made back in line 51. The interven- 
ing action takes place with these in view. With this call they are 
erased from the screen. The purpose of this scheme is to simply 
maintain the aircraft in view while it is being shot at and/or drop- 
ping a bomb. 

At this time the tank is displayed, line 57. The call to puti- 
mage() is followed by a screen edge test. If the tank is at a limit its 
direction flag is reversed. Note that the remainder of the loop is 
leaped over in this event. This to prevent the player from counter- 
acting the change before realizing it has taken place. 



Listing 6. The bomber aircraft group for the TANK_WAR action game. 



left-to-right aircraft group, 
graphics library. 



/» BOMR.C 

** Construction of a three plane 

** A nodule of TANKWAR.C 

** Compiled with Turbo C version 2 

*/ 

linclude <stdio.h> 

tinclude <graphics.h> 

/* ** global declarations ** */ 
int leftbdcol - 10,leftbd_top - 20, riteb_col - 30; 
int leftbeltop, leftbe2_top, leftbe3_top; 
int leftbel_col, leftbe2_col, leftbe3_col; 
int bhl_hit - 0, bh2_hit - 0, bh3_hit - 0; 
extern char far *bomr; 

/* " Begin program -■ */ 
bomber ( ) 
< 

if(bhl_hit -- 1 It bh2_hit — 1 11 bh3_hit ™ 1) { 
leftbd_col +- 100; riteb_col +- 100; 
bhl_hit - 0; bh2_hit - 0; bh3_hit - 0; } 

/* ** begin animation ** */ 
/* ** draw first bomber ** */ 

leftbel_col - leftbd_col; leftbel_top - leftbdtop; 
if(bhl_hit " 0) draw_bomber ( ) ; 
/* ** draw second bomber ** */ 

leftbd_col -- 10; leftbdtop +» 20; riteb_col -- 10; 
leftbe2_col - leftbd_col; leftbe2_top - leftbd_top; 
if(bh2_hit ™ 0) draw_bomber(); 
/* ** draw third bomber ** */ 

leftbd_col +- 25; leftbdtop +- 5; ritebcol +- 25; 
leftbe3_col - leftbd_col; leftbe3_top - leftbd_top; 
if(bh3_hit -» 0) draw_bomber(); 
/* ** advance to next position ** */ 

riteb_col -- 5; leftbd_col -- 5; leftbd_top ■ 20; 
if(riteb_col >- 299 ) { 

leftbd_col - 10, riteb_col » 30; 
} 
) 

/* ■■ erase bombers ■■ */ 
clr_bomrs ( ) 
< 

/* ** erase first bomber ** */ 
if(bhl_hit •- 0) 
putimage( lef tbel_col, lef tbel_top, bomr, XOR_PUT); 
/* ** erase second bomber ** */ 
if(bh2_hit »» 0) 

putimage(leftbe2_col,leftbe2_top,bomr,XOR_PUT); 
/* ** erase third bomber ** */ 
if(bh3_hit ~ 0) 

putimage) lef tbe3_col, lef tbe3_top, bomr, XOR_PUT); 



/* " draw bomber aB sequence of h/v lines 
draw_boinber( ) 



•/ 



putimage ( lef tbd_eol , lef tbd_top , bomr , COPY_PUT ) ; 
> 



The remainder of the loop is concerned with keyboard input. A 
challenge was how to interpret the closure of any key, ASCII or 
non-ASCII, without echo with a single key press. We can do this 
using the function rd_nonasky() because of the manner interrupt 
16H reads the keyboard. The non-ASCII keys place a in register 
AL and an integer for the key in AH. An ASCII key press places 
the ASCII value in AL. 

The first requirement is to check the keyboard for a closure. If 
there is none waiting there is no point in going on to the end of the 
loop. If kbhit() has a value of zero the program returns to the 
beginning of the loop. If a non-zero value exists a check is made of 
the keypad arrow keys, 4,6, and 8. If one of these non-ASCII keys 
has been pressed its value is in variable n_asc. If this is not the case 
either a meaningless key or an ASCII key has been pressed. As- 
suming an ASCII key closure its char value is assumed by the 
variable run. Pressing the Q key exits the program. 

Now that we have looked at how the program control performs 
let's make a quick review of the four supporting modules. 

The Game Object Construction Module 

The constructions in GME_FIGS.C all use putimageQ. To 
date I have not found a way to combine putimage() with viewports 
in animation without the whole thing blowing up. Viewports do 
work with putimage() for static displays, such as the game scoring 
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Listing 7. The BOMBS module for the TANKWAR action game 



0, drp3_flg - 0; 

1, bom3_flg - 1; 

73; 



/* BOMBS.C 

*« The bombs module for TANK_WAR.C. 

** Compiled with Turbo C version 2.0 graphics library. 

*/ 

(include <graphics.h> 

/* ** global declarations ** */ 
extern char far *bomb; 
extern char far *burst; 
extern char far *tank; 
extern int leftt_col; 

extern int leftbel_col, leftbe2_col, leftbe3_col; 
extern int bhl_hit, bh2_hit, bh3_hit; 
int tnk_hit - 25; 
int tnk_hit_flg - 0; 

/* •• begin program ■" */ 
drop_bombs ( ) 

{ 

static int xa ■ 0, ya ■ 0; 
static int drpl_flg - 0, drp2_flg 
static int boml_flg "1, bom2_flg 
static int xbmbl,xbmb2,xbmb3; 
static int ybmbl - 65,ybmb2 - 69,ybmb3 
/* ** begin animation ** */ 
/* ** bomber 1 bomb drop ** •/ 
if(bhl_hit -- tt (leftt_col-leftbel_col) 
<« 40 tt boml_flg -- 1) { 
drpl_flg - 1; boml_flg - 0; 
xbmbl - leftbel_col +6; ) 
if(drpl_flg -- 1) { 
bmbl_drp( xbmbl, ybmbl) ; 
ybmbl +-6; ) 

if (ybmbl >- 189 || (ybmbl >- 189 St xbmbl 

>» leftt_col St xbmbl <- leftt_col +20)) ( 
xa - xbmbl; ya - 189; 
bburst ( xa , y a ) ; { 

drpl_flg - 0; bomlflg » 1; ybmbl - 65; 
}> 
/* ** bomber 2 bomb drop ** */ 
if(bh2_hit -- tt (leftt_col-leftbe2_col) 
<- 40 tt bom2_flg ™ 1) { 

drp2_flg - 1; bom2_flg - 0; 
xbmb2 - leftbe2_col +12; } 
if(drp2_flg -- 1) { 
bmb2_drp(xbmb2 ,ybmb2 ) ; 
ybmb2 +- 6; } 

if(ybmb2 >- 189 || (ybmb2 >- 189 tt Xbmb2 

>» lefttcol tt xbmb2 <- lefttcol + 20)) { 
xa - xbmb2; ya - 189; 
bburst(xa,ya) ; { 

drp2_flg ■ 0; bom2_flg - 1; ybmb2 - 69; 
>) 
/* ** bomber 3 bomb drop ** */ 
if(bh3_hit « tt (leftt_col-leftbe3_col) 
<- 40 tt bom3_flg " 1) { 
drp3_flg - 1; bom3_flg - 0; 
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xbmb3 - lef tbe3_col+6 ; 
if(drp3_flg — 1) { 
bmb3_drp ( xbmb3 , ybmb3 ) ; 
ybmb3 +-6; } 

if (ybmb3 >- 189 | | (ybmb3 >- 189 tt xbmb3 

>- leftt_col tt xbmb3 <- leftt_col + 20)) 
xa " xbmb3; ya - 189; 
bburst ( xa , y a ) ; { 

drp3_flg - 0; bom3_flg - 1; ybmb3 - 73; 
>> 
> 

/* «* display shell burst «• */ 
bburst (short xa, short ya) 

I 

if(xa >- lefttcol tt xa <- leftt_col + 20) 

putimage ( lef tt_col , 189 , tank , XOR_PUT ) ; 

putimage(xa,ya, burst, COPY_PUT) ; 
/* ** ring bell ** */ 

sound(1000) ; 

delay (50); 

sound(1500); 

delay(50); 

sound(2000) ; 

delay(50); 

sound(lOOO) ; 

delay (50); 

nosound ( ) ; 
putimage(xa, ya, burst, XOR_PUT) ; 
if(xa >» leftt_col tt xa <- leftt_col + 20) { 
putimage ( lef tt_col, 189, tank, COPY_PUT); 
/* ** update tank hit scoring ** */ 
tnk_hit_flg - 1; tnk_hit -- 1; > 

) 

/* ™ draw descending bomb 1 figure — */ 
bmbl_drp(int xbmb,int ybmb) 

{ 

put image ( xbmb , ybmb , bomb , COPY_PUT ) ; 

delay (15); 
putimage ( xbmb , ybmb , bomb , XOR_PUT ) ; 

> 

/* -- draw descending bomb 2 figure ™ */ 
bmb2_drp(int xbmb, int ybmb) 

{ 

putimage ( xbmb , ybmb , bomb , COPY_PUT ) ; 
delay(15) ; 
put image ( xbmb , ybmb , bomb , XOR_P0T ) ; 

} 

/* ■■ draw descending bomb 3 figure ™ */ 
bmb3_drp(int xbmb, int ybmb) 

{ 

putimage (xbmb, ybmb, bomb, COPY_PUT) ; 

delay (15 ), • 
putimage (xbmb, ybmb, bomb, XOR^PUT) ; 



to be developed in the next of the series. But even with these 
problems can develop. 

The library graphics do have a bad feature in that the construc- 
tion of each object is accompanied by a brief flash of its image at 
the screen's HOME position. To date I have not found a way 
around this. Hopefully someday. 

Five play objects are created in this module: the tank, a 
bomber, the shell fired from the tank, the bomb dropped from a 
plane, and the burst resulting from an exploding shell or bomb. 
They are declared as far pointers in lines 8 - 12. The declarations 
must be global. All the modules are created in the one function, 
drw_figs(). Two declarations are required: a buffer to store the 
image temporarily, and an unsigned variable to hold the imagesize. 
All of the play objects are constructed from straight line segments. 
After the object's design is specified the storage need is deter- 
mined, the buffer allocated, and the image stored using a call to 
getimageO- This is followed by a brief flash on clearing the screen. 

The BOMRfJ Module 

When we look at Listing 6, we see that lines 20-31 have 
responsibility for displaying each of the three planes. To get to this 
point, however, a preliminary screening process takes place in lines 
17 -19. Again a reliance on flags (BH stands for Bomber Hit). The 
AND (&&) logic reports if all the bombers have been shot down. 



If that is so, they must be re-constructed. New screen coordinates 
are assigned as offsets in a brazen attempt to confuse the player on 
just where it is they may re-appear. 

If we have shot down a bomber we jolly well do not want it to 
continue on its trek across our screen. We want it to go away! 
Right? So if the flag is set to the plane appears. When a plane 
receives a shell hit, as we shall shortly learn, its hit flag is set to 1. 
In which case it is not drawn. 

So why are its column coordinates updated as though it were 
really present? So the program will always know where it should 
be, even if it is not visible, that's why. Just a simple matter of 
keeping track for its later re -appearance. Bomber drawing is per- 
formed with putimage() in its COPY_PUT action constant mode. 

After our bombers have been drawn and been shot at, assum- 
ing they were not shot down, they have to be advanced to the next 
location on screen. It is a good idea to erase the existing image 
prior to displaying another at its new location. The function 
clr_bomrs() attends to that. Erasing is performed with putimage() 
in its XOR_PUT action constant mode. 

The BOMBS Module 

When it comes to dropping bombs there are a lot of flags and 
other variables to keep track of. When you think about it, bombs 
do require some conservation. We shouldn't just sprinkle them 
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Listing 8. The SHELL FIRING module for the TANKWAR action game. 


1: /* SHELL. C 


63: 


/* *« test for hit on bomber 1 " */ 


2: 


** Program to animate an artillery shell in any on* 


64: 


if(bhl hit -- 0) ( 


3: 


** of four angles: 50, 70, 110, or 130 degrees. 


65: 


if(xb >- leftbel_col tt xb <- leftbel_col + 20 


4: 


** A nodule of TANK_WAR screen action game. 


66: 


tt yb >- leftbel top tt yb <- leftbel_top + 20) 


5: 


** Compiled with Turbo C version 2.0 graphics library. 


67: 


{ 


6: 


*/ 


68: 


sburst(xb+10,yb-10) ; 


7: 


1 include <stdio.h> 


69: 


putimage ( lef tbel_col , lef tbe l_top , bomr , COPY_POT ) ; 


8: 


(include <graphics.h> 


70: 


putimage ( lef tbel_col , lef tbe l_top , bomr , XOR_PUT ) ; 


9: 


void sburst( short xl, short yl); 


71: 


putimage ( xb , yb , she 1 1 , COPY PUT ) ; 


10: 


/* ** global declarations ** */ 


72: 


flite_flg - 0; 


11: 


extern int leftt_col, ritet_col; 


73: 


bhl_hit - 1; pla_hit +- 1; score +- 100; 


12: 


extern int bhl_hit, bh2_hit, bh3_hit; 


74: 


return; }} 


13: 


extern int leftbel_col, leftbel_top; 


75: 


/* ** test for hit on bomber 2 ** */ 


14: 


extern int leftbe2_col, leftbe2_top; 


76: 


if(bh2 hit — 0) { 


15: 


extern int leftbe3_col, leftbe3_top; 


77: 


if(xb >- leftbe2_col tt xb <- leftbe2_col + 20 


16: 


extern int drpl_flg, drp2_flg, drp3_flg; 


78: 


tt yb >- leftbe2_top tt yb <- leftbe2_top + 20) 


17: 


extern int Xbmbl,xbmb2,xbmb3,ybmbl,ybmb2,ybmb3; 


79: 


{ 


18: 


extern char far *shell; 


80: 


sburst(xb+10,yb-10) ; 


19: 


extern char far *burst; 


81: 


putimage ( lef tbe2_ool , lef tbe2_top , bomr , COPY_PUT) ; 


20- 


extern char far *bomr; 


82: 


putimage ( lef tbe2_col , lef tbe2_top , bomr , XOR_PUT) ; 


21 


int score "0; 


83: 


putimage(xb,yb, shell, COPY_PUT) ; 


22 


int pla hit "0; 


84: 


flite_flg - 0; 


23 


int flite fig - 0; 


85: 


bh2_hit - l;pla_hit +- 1; score +- 100; 


24 


int shl_bal - 150; 


86: 


return; }} 


25 


int shl_fir_flg - 1; 


87: 


/* ** test for hit on bomber 3 ** */ 


2C 


/* ■" Begin program ■■ */ 


88: 


if(bh3 hit — 0) { 


27 


shel(char tnk_shl) 


89: 


if(xb >» leftbe3_col tt xb <- leftb*3_col + 20 


28 


{ 


90: 


tt yb >- leftbe3 top tt yb <- leftbe3_top + 20) 


29 


if(tnk_shl l» •*' at tnk_shl 1- "S" 


91: 


{ 


30 


at tnk_shl 1- •!>• tt tnk_shl 1- 'F') return; 


92: 


sburst(xb+10,yb-10) ; 


31 


/* ** begin animation ** */ 


93: 


putimage ( lef tb*3_col , lef tbe3_top , bomr , COPY_PUT ) ; 


32 


dis_pla_shl ( tnk_shl ) ; 


94: 


putimage ( lef tbe3_col , lef tbe3_top, bomr , TOR_PUT ) ; 


33 


> 


95: 


putimage(xb,yb, shell, COPY_PUT) ; 


34 


/* -- display shell burst ■■ */ 


96: 


flite_flg - 0; 


35 


void sburst( short xa, short ya) 


97: 


bh3_hit - 1; pla_hit +- 1; score +- 100; 


36 


{ 


98: 


return; }} 


37 


putimage ( xa-5 ,ya-5 , burst , COPY_PUT ) ; 


99: 


} 


38 


/* ** ring bell ** */ 


100: 


/* ■» read key and fire shell ■■ */ 


39 


sound(1000) ; 


101: 


dis_pla shl(char shl_ang) 


40 


delay (50); 


102: 


{ 


41 


sound(lSOO); 


103: 


int x - leftt col + 10, y - 179, ang_flg; 


42 


delay (50); 


104: 


flite_flg - 1; shl_fir_flg - 1; shl_bal -- 1; 


43 


sound(2000) ; 


105: 


switch ( shl_ang ) { 


44 


delay(50); 


106: 


case 'A': { ang_flg ■ 1; break; } 


45 


: sound(1000); 


107: 


case ■ S": ( ang_flg - 2; break; } 


46 


: delay(50); 


108: 


case 'D': { ang_flg - 4; break; } 


47 


: nosound ( ) ; 


109: 


case T": { ang_flg - 5; break; } 


48 


: putiaiage ( xa-5 ,ya-5 , burst , XOR_ PUT ) ; 


110: 


default: return; 


49 


: > 


111: 


) 


SO 


/* ™ create basic shell — */ 


112: 


while(flite_flg) { 


51 


: tshell(int xb, int yb) 


113: 


if(ang_flg — 1) { x -- 4; y —5; tshell(x,y); 


52 


: { 


114: 


if(flite_flg — 0) break; } 


53 


: int xbs " xb, ybs - yb; 


115: 


else if(ang_flg —2) { x -- 3; y --5; tshell(x,y); 


54 


/* ** display and erase shell ** */ 


116: 


if(flite_flg — 0) break; } 


55 


putimage ( xb , yb , she 1 1 , COPY_PUT ) ; 


117: 


else if(ang_flg — 4) { x +- 3; y --5; tshell(x,y); 


56 


: hit_tst ( xbs , ybs ) ; 


118: 


if(flite_flg -- 0) break; ) 


57 


: delay (8); 


119: 


else if(ang_flg — 5) { x +- 4; y --5; tehell(x,y) ; 


58 


: putimage ( xb , yb, shell, XOR_PUT) ; 


120: 


if(flite_flg -- 0) break; } 


59 


: ) 


121: 


if(y <- 22) { flite_flg - 0; return; } 


60 


: /* ■- test for aircraft hits ■■ */ 


122: 


) 


61 
62 


: hit tst(int xb,int yb) 
: { 


123: 


) 



like wildfires across the screen in hopes of knocking out a tank. So 
it's back to decision making logic again. The variable declarations 
are all static as their values must be maintained between function 
calls. 

Bombs descend in steps of six pixel increments. We have first 
of all to make sure there is a plane available. Then its screen 
position relative to its target, the tank, has to be checked. If these 
tests are positive and a bomb flag, bomi_flg, is enabled, where the i 
is 1, 2, or 3 depending on the aircraft, a drop flag, drpi_flg, is 
enabled. At this time the bomb flag is cleared, else next time 
around a new bomb may be dropped, ready or not. With each call 
to drop_bomb() the bomb makes a descent until it strikes the tank 
or the "ground." At that point the burst function is called with the 
burst coordinates and the flags are set up for the next drop. 

There is a complication with the screen images when one inter- 
sects another, such as when a bomb or shell strikes an object. First 
we want the shell to go away. Then we want the burst to appear 
overlaying the object underneath, if any. Then, if there has been a 
hit on an object it has to go away. Well, the XOR_PUT action 



constant for a given object does not necessarily affect another. 
Without some cleanup provisions our screen is quickly littered 
with debris, sort of like the space junk now orbiting the earth. So 
as part of the cleanup procedure lines 92 and 94 clean up the 
debris from bomber 1 by a quick draw and erasure. Even so there 
will be an occasional display of lingering garbage, which is swept 
away by the next pass across the screen. 

The SHELL Module 

By now we have a pretty fair understanding of all the concerns 
to be considered in moving screen objects around. Even so the 
large number of global variables in this module may be a surprise. 
This simply because there is so much to keep track of. First we 
have to know where the tank is when the shell is fired. Shells 
mysteriously appearing from out of nowhere are not uncommon in 
working out some of these coordinate schemes. And as the little 
guy goes streaking off into the sky its motions require continuous 
draw, delay, clear, advance instructions. 

The actual shell firing takes place in the last function, 
dis_pla_shl(char shl_ang), beginning at line 101. The only flag 
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actually used at this time is the flite_flg which maintains the shell in 
a transit loop. The shl_fir_flg and variable shl_bal are used for 
scoring. This istrue for the variables plajiit and score as well. The 
scoring of hits and keeping track of shells fired is actually relatively 
simple. The reason for not including them at this time is that their 
display on the screen is not. 

The shell may or may not hit one of the bombers. So the rela- 
tion of each bomber to the shell must be maintained. With each 
shell advance detection logic must test for an intersection. The 
testing is performed in the function hit_tst(), beginning on line 61. 
As we saw in the BOMBS module the putimageO action constants 
COPY_PUT and XOR_PUT perform debris cleanup. 

It may come as a surprise that a burst function is included in 
two modules. This is largely as a matter of convenience for passing 
location variables. 



Summary 

We have learned that bringing all the play object action to- 
gether on our screen does involve a fair amount of complexity. 
Since activities of this kind require a lot of program code it is to 
our advantage to write individual modules and link them together. 
The Turbo C MAKE utility is of considerable assistance in the 
compiling and linking operations. 

This article of necessity starts right out with the completed 
modules. 

In a real development each play object is written in a stand- 
alone mode to verify its construction. When we are satisfied with 
its performance it is revised for linking in with the overall program. 
The interactive logic must be developed with the entire system, 
but doing what can be done in the stand-alone mode eases this 
task. • 
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Real Computing 

The National Semiconductor NS320XX 

by Richard Rodman 



Metal 0.6 

Version 0.6 of Bare Metal is available now. It has been com- 
pletely transformed through the use of a new assembler by Bruce 
Culbertson. It is now linked together from separately-assembled 
or compiled modules. Phil Prendeville's C compiler has been 
modified for compatibility with the assembler. 

Metal is now being distributed as a complete cross develop- 
ment package for a PC. For example, if you want to put the system 
in a directory C:\NS32, put the floppy in the A; drive, and enter 
the command: 

install c: ns32 

Notice the space between the C: and the NS32. MS-DOS has 
such a stupid command interpreter that the drive and the directory 
have to be passed as separate items. 

At any rate, along with the compiler and assembler you also get 
a make utility, a new version of the host program, an EPROM 
utility, and other miscellaneous utilities. Naturally, source code is 
provided for everything. BlOSes are provided for the Cromemco 
16FDC and for the PD-32 coprocessor board. 

The new version of host supports the TDS download format. 
(The previous one claimed to, but testing showed that it didn't.) 
The simple ROM monitor, SRM, has been modified to allow TDS 
download format and commands. 

Work is under way to supply a complete C library and include 
files. This will allow the compiler and assembler to run in native 
mode, and a PC will no longer be necessary. 

There are a number of major internal changes in version 0.6. In 
order to get around the address-constant problem, we've basically 
given up and created a new kind of executable that executes at a 
CP/M-like TPA address of 010000 hex (64K). These files should 
be linked as follows (for a hypothetical program myprog): 

Id -e main -T 010000 -o myprog. e myprog. o -lc 

Not very user-friendly, you say? All suggestions and help are 
welcome! 

Executables generated in the .E32 format, which are com- 
pletely relocatable, are still supported. Hopefully, in the future, an 
approach to solving the address constant problem can be deter- 
mined that will not require the TPA restriction; unless you have an 
MMU (not currently supported), only one program can be run- 
ning at a time, like CP/M. 

Another internal change is that the single-character I/O system 
calls are no longer supported. They just turned out to be too inef- 
ficient. New system calls for the seek and tell functions (get and set 
read/write position in a file) have been added. 

Rules for 360s and 1.2s 

There are two simple rules for exchanging floppies between 
360 KB and 1.2 MB floppy drives. These are as follows: 



1. If you format it on the 360, you can write it on the 360, but if 

you ever write it on the 1.2, you can't read it on the 360 
anymore. 

2. If the floppy has never, ever been formatted on any drive, and 

you format it /4 on the 1.2, you can write it on the 1.2; but if 
you ever write it on the 360, and then write it on the 1.2, you 
can't read it on the 360 anymore. Reformatting on the 1.2 
won't help; if you reformat on the 360, see rule number 1. 

Remember that any writing to the disk involves writes to the 
directory, too, so don't imagine that "accessing different files" will 
keep you safe. 

Maybe it's about time we say to heck with the silly nonsense 
and standardize on 3.5 inch floppies! 

Speaking of standards, I recently saw a Zenith MinisPort, and 
was pleasantly surprised. The keystroke feel was nice, the display 
was quite easy to read (it's adjustable to any angle), the 2-inch 
floppy is kind of spiffy, and the thing is amazingly light and small! 
Why are all the reviewers so intent at bad-mouthing it? Because it 
has a lowly 8088 processor, I suppose. Tests with laboratory ani- 
mals have proved that using a faster CPU actually increases typing 
speed. 

ICU test comments 

The ICU test program presented in a previous column will not 
work on the PD-32 board. It seems that the H-counter is used on 
the PD-32 board to control dynamic memory refresh. The gen- 
eral-purpose I/O bits of the ICU are used to control various other 
functions of the board, so be careful. 

The CD conspiracy 

There are two shocking facts about CDs that are being kept 
secret by a mammoth conspiracy. Tell everyone you know! 

First, CDs are by no means indestructible. The CD contains a 
very thin top layer (the printed side), which is very delicate. So 
delicate, in fact, that thumbnails pressing on, or even small objects 
pressing on or dropped on this side will destroy the disk. 

Worse, however, is the Notch. It seems that some people in the 
entertainment industry wanted a copy-protection scheme for the 
DAT (Digital Audio Tape) in which there would be a 45 dB notch 
at 15 kHz. Essentially, frequencies in that region would be com- 
pletely wiped out, which (as any audio buff will tell you) will cause 
distortions throughout the rest of the spectrum. 

As with all copy-protection schemes, this idea punishes all le- 
gitimate users without really impacting any illegitimate ones; but 
the entertainment industry is a more monopolistic and openly op- 
pressive cartel than the computer industry has ever had. They tried 
to get Congress to force this on everyone, but fortunately this 
attempt failed. 

But here's the sickening part: The electronics industry is doing 
it anyway! Not only do all DAT decks incorporate the Notch, but 
more and more CDs are being produced and distributed recorded 
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with the Notch. 

A Real Computer 

Dave Rand, the designer of the PD-32 board, has designed a 
new board which is considerably more powerful. It has a 32532 
CPU equipped with up to 32 megabytes of no-wait-state, page- 
access SIMM DRAM. It has 8 serial ports. It has two SCSI ports, 
one for a disk and/or tape, and one for other uses. It also can be 
equipped with a 32381 math coprocessor. The system is offered as 
an unpopulated four-layer printed circuit board for $200. If you're 
•interested, contact him at the address below. 

Bruce Culbertson and others are working on porting Minix to 
the board, and are reported to be close to finished. He is working 
on an add-on board to include an Ethernet port and 16 additional 
serial ports. 

The design of this board really gets around a lot of the limita- 
tions of the Designer's Kit board, mainly limited RAM and I/O. 
After all, what good is a fast processor if you can't get data in and 
out of it? 

What, after all, makes a system fast? We've all seen 8080 sys- 
tems that offer lightning response— and 386 systems that move 
like glaciers. For a really fast system, all components have to be 
tuned together, including the software. 

State machines 

Tuning implies music, and music implies rhythm. In an embed- 
ded system, it often doesn't matter so much how fast you do some- 
thing, as how close to the right time you do something; so, embed- 
ded systems are often designed around a synchronous, tick-derived 
state machine. Such a design yields a deterministic— accurate and 
predictable — response. 

However, a synchronous state machine does not lend itself to 



dynamic, constantly-changing systems such as general-purpose 
computers. Many modern multitasking kernels offer a hybrid ap- 
proach, where tasks can be implemented as synchronous state ma- 
chines or as dynamic tasks. 

It has been considered a truism that real-time operating sys- 
tems make poor development environments. Real-time operating 
systems cannot allow priorities to be changed; they can't allow vital 
tasks to be swapped; they can't use high-overhead, dynamic-block, 
multiply-indirect file systems. However, I think as the kernel de- 
sign advances, as processors get better, and as the low-overhead 
system design approach catches on, we'll see systems with all of the 
friendliness of Unix (or more, hopefully) that really are suitable 
target environments for real-time systems. What would be really 
great is if you had binary compatibility from the bottom of the line 
to the top, like the VAX, but in a micro. 

Next Time 

Futurebus: Is it going places, or taking people for a ride? • 

Where to Call or Write 

BBS: 1-703-330-9049 
Dave Rand, 1-408-733-4125 



User Disk 

The complete installation package of Metal 0.6, includ- 
ing C compiler, assembler, linker, make utility, ROM moni- 
tor, host program, and various utilities, is available on 3.5" 
1.44MB, 3.5" 720K, or 5.25" 360K PC format disks for $13 
postpaid in the U.S. 
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You'll hear more about these products here, but contact 
them for more information in the meantime. 
Ampro Little Board Returns 

The Ampro Z80 Little Board which had been out of pro- 
duction has been picked up by Davidge Corporation, 94 Com- 
merce Drive, Buellton, CA 93427, Phone (805) 688-9598. 
Dean Davidge has been producing his own line of single board 
computers for quite a while. I had one of his Z80 boards and 
it was a fine product, so he should do a good job with the 
Ampro LB. 

Davidge is providing repair service for units made by both 
Ampro and Davidge. They can also provide the Project 
Board/80, CP/M and ZCPR3, BIOS Source, and manuals. As 
far as I know, this is one of the last CP/M computers still in 
production— support them if you want a source to be avail- 
able in the future. 

Another Davidge product line is the RIM (Remote Inter- 
face Multiplexer) Bus series of data collection and control 
cards. 

Now that the Ampro LB is again available, I would like to 
develop a ROM based system to use the card as an embedded 
stand alone controller. This will be for controller applications, 
not desk top computer applications, and will be very different 
from the usual CCP, BIOS, and BDOS. Any one else inter- 
ested in this? • 
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it's somewhat painful to interface with in- 
dustrial-class devices, such as milling ma- 
chines, motors, sensors, etc.; and floppies 
don't work well in oily, smoky, electrically 
noisy or corrosive environments. However, 
I believe the PC sets expectations as to 
price and performance. "Why should I buy 
a $1000 single-board computer when I can 
get an AT for that price?": never mind 
that the AT couldn't do the job half as 
well. And can you build a floppy controller 
for $19, or a video card for $25? This 
trend will only get worse as new XTs drop 
in price, and used XT are pushed out of 
industrial use by cheap AT-class machines 
(or RISC machines as Lee suggests). 

Actually, my more interesting argu- 
ment is not that IBM-type PC's are cheap 
end-use systems; they are cheap develop- 
ment systems. There are good reasons 
that chip manufacturers sell their develop- 
ment tools to run on PCs. Typically, a PC- 
compatible processor development pack- 
age includes a plug-in card, assembler, de- 
bugger and docs for several hundred dol- 
lars and up, with $1000 a common price. 
PC-class cross-compilers for C (and occa- 
sionally other languages) are available for 
a few to several hundred dollars and up. 
There are even shareware sources for a 
few cross-compilers, with registrations un- 
der $100. And there are more and cheaper 
tools for native development of 8088-class 
applications. 

However, I have to admit that running 
a C cross compiler on a PC to cram code 
into the 4K program space of an 8051 
which will operate a voice-responding 
home security system is a bit of overkill. 
And, as it turns out, a lot of work to con- 
vince the compiler not to use the "huge" 
model of 1 gigabyte addressing to make 
the code fit at all! The engineer or pro- 
grammer becomes very removed from the 
application when you are designing a 
"talking doorknocker" from a screen/disk/ 
keyboard environment. And for "high- 
powered" applications with multiple proc- 
essors in constant communication, the ge- 
neric cross-compiler/simulator is not very 
useful: the development system usually is 
the application system. 

I think the answer is a modular devel- 
opment environment, where you assemble 
physical and software resources as needed. 
It could be as small as a few modules on 
your desk and a calculator-like interface; 
or as large as a PC connected to several 
processors. Lee Hart may have something 
with his "Z80 on a shingle" product and 



his "spreadsheet" programming meta- 
phor. Now, if I can only get him out of the 
"2K teensie-weensie BASIC" world of de- 
velopment systems, we might get some- 
where! 

I have more thoughts on the subject, if 
your readers are interested, but I have to 
get off my PC-AT and go into the base- 
ment to check my memory test run on 
some customer's S-100 IMSAI 32K 
DRAM boards. The "heat test" hairdrier 
sometimes slips off and starts cooking my 
8-inch floppies! 

Herb Johnson 

Forth Advocate 

I am impressed with your publication 
to the extent that I must congratulate the 
staff for a job well done! The contributors, 
both regular and otherwise, usually ac- 
complish their duty of generating fascinat- 
ing and useful articles. Moreover, I feel 
compelled to contribute as well. I see you 
would like more contributors and am curi- 
ous about your format preferences. Do 
you have any? I have such documents for 
various publications and would rely on 
them for any assistance otherwise. EDN, 
Personal Engineering, and Micro Cornu- 
copia are the others I speak of, and as you 
may well know they all have different "fla- 
vors." 

As long as I mentioned Micro Cornu- 
copia, I must say I do not wish TCJ to 
become The Last of the Mohicans 
amongst the various magazines still ori- 
ented towards serious fringe computing. 
That is why I must contribute along with a 
general support of the advertisers, etc. 
You WILL receive a manuscript or two 
from me. I just need to get up off my rear 
to do it. I'm quite sure most other TCJ 
readers have other things to do, besides 
document their personal projects. Al- 
though, after going through the work of a 
project, documentation and publication 
really is worth it. It's a great way to make 
contacts and gain a reputation. Not to 
mention the satisfaction gained by the edi- 
torial approval. 

As far as suggestions go, I would like a 
Neural Network article that is practical. 
I've contacted Dave Weinstein about his 
OOF (Object Oriented Forth) efforts and 
thought that OOF would be a good way of 
going about it. You may well agree. I am 
glad that Forth is a mainstay of TCJ. You 
can bet that I always hope Forth comes in 
every issue I receive! Also, the slant to- 
wards microcontrollers lately has been wel- 



come. My main gripe about most articles 
in Embedded Systems Programming is that 
they are not very practical or useful. 
Pseudo code may be a good thing to some, 
but to me it seems quite useless. I like ar- 
ticles with schematics and real code, not 
fairy tails. Another thing I have been inter- 
ested in lately is the CEBus development 
and articles in Circuit Cellar INK about 
them. Maybe that would be an opportu- 
nity for some people to contribute. 

Anyways, I won't waste any more of 
your paper. Keep up the excellence and 
thanks. 

Ronn Guttmann 
Australia 

Editor's Note: Our Forth authors are all 
overloaded with work, so there are no Forth 
articles in this issue— but there are more 
coming. 
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Make certain that TCJ follows you 
to your new address. Send both old and 
new address along with your 
expiration number that appears on 
your mailing label to: 

THE COMPUTER JOURNAL 
190 Sullivan Crossroad 
Columbia Falls, MT 59912 

If you move and don't notify us, TCJ 
is not responsible for copies you miss. 
Please allow six weeks notice. Thanks. 
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need to be in place and followed. We have 
a big problem now with the use of "C". 
Many organizations have gone to "C" as 
the solve all language. They feel by using 
"C" there is no need to institute all the 
standards I talk about. The truth is just the 
opposite. Unreadable and undocumented 
"C" code is just as possible as any other 
type of coding. You need standards for 
your own programmers and any outside 
consultants. We have treated software as a 
magical art, but in fact it is a simple sci- 
ence like many others. When we buy a car, 
you know you can go an buy a shop man- 
ual for it. That shop manual shows you 
how things go together, are repaired, sche- 
matics for trouble shooting, and basically 
the scientific rules by which the car was 
created. A software product should have 
nothing less than a "shop manual" as well. 

EXORMACS 

A few last comments on the Motorola 
Exormacs assembler. There are two items 
about that assembler which are important 
for our readers. The last ten years of work 
was done using the Exormacs assembler. I 
have gone to the Avocet assembler on the 
PC to replace the use of the Exormacs. In 
doing so I have discovered many things. 
The most important is how poor the Exor- 
macs is as an assembler. 

Some of the modules that assemble 
properly on the Exormacs will produce 
several hundred errors. At first I thought it 
was just minor differences between the 
Exormacs and the Avocet. Instead I have 
learned that the difference is due to lim- 
ited error checking on the part of the Ex- 
ormacs. I am now a confirmed believer 
that your assembler should have good 
tight error checking. As part of the ab- 
sence of personal controls, the past pro- 
grammer exploited all the loose structures 
the Exormacs assembler allowed them to 
use. 

A recent case in point has to do with 
DC statements. DC statements allocate a 
place in memory and set what is stored 
there to a defined value. A DS statement 
however just sets the space aside, typically 
setting it at zero value. When a table of 
variable values is desired you can include 
that table by using the DC statements and 
the corresponding desired value. If you 
want tables in which an offset or pointer 
into the table is used instead of the exact 
address you typically will use DS state- 
ments to define the pointers into that 
table. 



Those are the rules which the Exor- 
macs manual states. If an "offset" value is 
placed at the beginning of the DS defini- 
tions, then the assembler will equate point- 
ers for those defined items. Later you can 
use the defined items as pointers or offsets 
that are added to a register to fetch or 
change a value stored in that location. The 
assembler however should error out if a 
DC statement is given an "offset" value. 
The problem is an offset forces addressing 
to start at zero location, and as such you 
are directing the assembler to put specific 
values at those locations. 

Well it turns out the Exormacs allows 
DC statements with "offsets" of zero. This 
is completely opposite of what the manual 
states. What actually happens is the as- 
sembler treats the DCs as if they were 
DSs. It returns pointers if we give the DCs 
a zero offset, but addresses if no offset is 
used. When the same code is used on the 
Avocet crossassembler hundreds of errors 
get produced because it adheres to the 
rules. It forces you to create lists of offset 
pointers different from the list of values to 
be stored there. For me it has made things 
more difficult, because not only must I 
now make two lists of pointers, but I have 
to seek out these differences wherever 
they maybe in 4 megabytes of source code. 
It really is a management of information 
problems. It makes it hard to find out 
which module is actually defining the 
space and which modules are just using 
the same list of DCs for offset pointers 
(they all use the same include file). With 
two separate lists, I can see the users from 
the source quickly and easily. 

The biggest concern is the lack of error 
checking. If use of DCs with an "offset" is 
an error, say so. I have since found many 
cases where the assembler will just put 
what it thinks should go there instead of 
erroring out. What it thinks should go 
there and what you need to go there to 
make it work, may in fact be two different 
things. If I say do this, and that is not cor- 
rect, I want to know! Without good error 
checking you may find yourself with bugs 
that are assembler generated, and can be 
solved only by disassembling the produced 
code. I have spent many hours of late 
doing just that. What I have discovered is 
a lot of places in which the code is not 
what was assumed or desired. 

Because the managers of the project 
had so little control over the programmers, 
nobody has ever checked to see what the 
assembler produced. Their solution to 
bugs was adding more code to make up 
for the unknown source of the bug (the 



assembler we now know). Based on the er- 
rors I have seen on the Avocet, I guess 
there may be as many as 1000 lines of 
code improperly assembled that exist in 
the 50,000 lines of source code. To make it 
worse, I may have to find every one of 
those errors, before it can be assembled 
on a new assembler. No simple task. 

Till Later 

We spent this whole time on program- 
ming, but I think it is important. If your 
business is based on a software product, I 
hope you may look a little more seriously 
into what is happening within those 
begin...end statements. Next time I hope 
to talk about the Harris RTX2001A • 
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by Bill Kibler 



Another article with more on a hot 
topic (at least for me) — programming. It 
occurred to me I hadn't explained what or 
how you can determine if your program is 
well structured. So let's see if we can't give 
you some pointers into better code gen- 
eration and programmer management. 

Defining The Problem 

The reason I have been so much in- 
volved lately with what constitutes good 
and bad programming is my job. I work 
for a company who has 10 year old code 
and can not maintain it. I know that they 
are not unusual in any way. Lots of com- 
panies are finding themselves in this situ- 
ation. There are a number of mistakes 
they have all made and as we will see, 
some ways they could have prevented 
those problems. 

Let's talk about my current problems 
and how they got there. This is 68000 as- 
sembly language code. In many cases this 
was the first time any of these program- 
mers had written assembly language code. 
They knew only high level structures and 
imported them to the code whenever pos- 
sible. They have used macros in order to 
create the higher level structures they 
thought were needed. Many of the pro- 
grammers felt only they were capable of 
writing good code. Personality problems 
added to the way code was generated. 
Some of the original employees are still 
here and I can see how they are still mess- 
ing up the other programmers by forcing 
their concepts of good programming on 
them. 

Before I explain how to test good style 
from bad, what is bad programming. I 
have 10 years worth of code that is mostly 
unreadable. It runs on for pages and ap- 
pears to do nothing. They have used mac- 
ros which are not transportable to other 
assemblers. The have gone so far as to 
write their own computer language. To 
make it worse they have incorporated 
macros to talk to their own language. They 
use those special macros even when the 
code is going into ROMs that do not inter- 
face to their code. Since many of the pro- 



grammers have left the company, there 
are large sections of code in which we have 
no person to ask to find out what they are 
suppose to do. Documentation is almost 
non existent. There is not a single docu- 
ment that explains how the actual code 
works, which modules talk to which mod- 
ules, what method of passing data is used, 
or what the overall functionality of the 
program is. We can't rewrite the code be- 
cause we do not know what the code actu- 
ally does. 

How Not to Get There... 

The company got themselves in this 
problem for a number of reasons. Early 
on, the managers should have been in 
charge and were not. By this I mean, tak- 
ing control from your programmers. As a 
manager you need to know where the 
company is going, what the long term ob- 
jectives of the product are, need clear 
functional specifications of the product, 
and take charge of the project. A new 
manager here, has his programmers write 
specifications of the proposed code before 
any code is written. This is a good start. 

Where he and most places fall apart is 
checking on the actual code written. No- 
body here reviews the code once it is writ- 
ten. If it works, it becomes a product. That 
is how 10 years of really bad, but working 
code, has been keeping the company 
going. Now they want to keep their cus- 
tomers happy and are having real prob- 
lems fixing minor bugs and adding simple 
upgrades. What was needed all along was 
a review committee on written code. 

If you are a single programmer working 
on a project, you will know every bit of 
code. If however you are part of a group 
working together on a large project, your 
code must fit in with others and be read- 
able by them as well. The only way to 
guarantee that is to have the group review 
that code. For small groups everybody 
would get involved. For larger groups, 
committees of three or four would do. The 
main task for the manager is making sure 
the reviewers do it properly. 

Some simple guidelines are needed, 



and it is up to the manager to take charge 
and enforce those guidelines. Most of the 
code I see does work very well. The prob- 
lems come when that code is stuck into, or 
as the case may be not into modules. "Spa- 
ghetti" code typically has good sections, 
however those sections need to be "fac- 
tored" out. Factoring is breaking the code 
into smaller modules so that the same 
functions are not repeated hundreds of 
times with new code. 

What I have used for myself is a list of 
questions that need to be asked for every 
program you write or are involved with. 
The reviewers need to continuously ask 
these questions and use them as guide 
lines. They are: 

1) What will be needed if this code is ported 

over to another operating system, hard- 
ware platform, assembler, or program- 
ming style. 

2) What will happen if new features are 

needed, can they be added easily. 

3) Does the structure lend itself to easy main- 

tenance, how are minor changes made, 
can bugs be found and corrected eas- 
ily. 

4) Is the structure clearly defined and docu- 

mented so we can work on the project 
two years from now without major prob- 
lems. 

5) What happens if the lead programmer 

dies, moves, or gets sick. 

The last one is my favorite and usually 
causes the most problems. It becomes a 
problem when they answer back that "I 
will get it done after .... ", because that 
after never happens. As a manager you 
can not ignore these five concepts, doing 
so is a guarantee that your code will not be 
portable, maintainable, or repairable. A 
bottom line here is setting standards for 
your programming operation. 

Those standards involve how the code 
is written, not only in what language used, 
but style, version tracking, documentation, 
flow charting, testing, and generation. 
Clearly defined standards for these aspects 

(Continued on page 39) 
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